@aopslab/aops-cli 0.1.1 → 0.1.3

package/README.md

@@ -1,9 +1,19 @@
 # @aopslab/aops-cli
 
-AOPS Community operator CLI for an existing local or remote AOPS server.
+AOPS Community operator CLI. The global CLI controls the local AOPS server,
+including setup, start, stop, status, health, authentication, and agent-facing
+operations.
 
-Install globally with `npm install --global @aopslab/aops-cli`, or run once with
-`npx --yes --package @aopslab/aops-cli aops-cli --help`.
+```sh
+npm install --global @aopslab/aops-cli
+aops-cli --help
+aops-cli setup server-env
+aops-cli server setup --runtime native --postgres external --apply
+```
 
-The public source distribution is available with
-`git clone https://github.com/eeemzs/aops-community.git`.
+The npm installation includes the matching `@aopslab/aops-server` runtime, so
+the default setup path does not require Git or a source checkout. Advanced
+users can still run an explicit AOPS Community checkout with `--source-root`.
+
+Server data, configuration, credentials, logs, and lifecycle state are stored
+outside npm's package directory. PostgreSQL remains operator-owned.

package/THIRD_PARTY_NOTICES

@@ -1,13 +1,10 @@
-AOPS Community Product Third-Party Notices
-
-This file is generated deterministically from the exact production payload union.
-pnpm: 11.9.0
-pnpm lockfile: sha256:fb0c58e5687f5518b120c058a8dd1089682005bafdb3c77915a0fcf038b60cc2
-Platforms: linux/amd64, linux/arm64
-Payloads: server production deploy, separate CLI artifact production deploy, Cockpit emitted bundle
-Third-party packages: 295
-First-party source records excluded from the sections below: 31
-First-party registry packages excluded from the sections below: 22
+AOPS Community Third-Party Notices
+
+This file preserves the reviewed license notices for third-party components
+used by the AOPS Community CLI, server, and Cockpit. It is intentionally a
+conservative superset: a particular installation may use fewer components.
+The exact dependency closure of an npm server release is recorded in that
+package's npm-shrinkwrap.json.
 
 ================================================================================
 @drizzle-team/brocli@0.10.2

package/dist/aops-cli.mjs

@@ -12,11 +12,20 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
   if (typeof require !== "undefined") return require.apply(this, arguments);
   throw Error('Dynamic require of "' + x + '" is not supported');
 });
-var __esm = (fn, res) => function __init() {
-  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+var __esm = (fn, res, err) => function __init() {
+  if (err) throw err[0];
+  try {
+    return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+  } catch (e) {
+    throw err = [e], e;
+  }
 };
 var __commonJS = (cb, mod) => function __require2() {
-  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+  try {
+    return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+  } catch (e) {
+    throw mod = 0, e;
+  }
 };
 var __export = (target, all) => {
   for (var name in all)
@@ -70945,7 +70954,7 @@ function compareCore(left, right) {
   return 0;
 }
 function resolveCommunityCliIdentity(environment = process.env) {
-  const injectedVersion = true ? "0.1.1" : void 0;
+  const injectedVersion = true ? "0.1.3" : void 0;
   const version = nonEmpty(environment.AOPS_CLI_VERSION) ?? nonEmpty(injectedVersion) ?? "0.0.1";
   if (!validSemver(version)) throw new Error("community_cli_version_invalid");
   const injectedSource = true ? "public-release-bundle" : void 0;
@@ -84385,6 +84394,7 @@ function buildCommunityInstanceContract(input) {
 // apps/aops-cli/src/lib/community-native-lifecycle.ts
 import { createHash as createHash14, randomBytes as randomBytes8, randomUUID as randomUUID7 } from "node:crypto";
 import { spawn as spawn5 } from "node:child_process";
+import { createRequire as createRequire3 } from "node:module";
 import {
   closeSync as closeSync8,
   existsSync as existsSync13,
@@ -87308,6 +87318,7 @@ var COMMUNITY_STRICT_MIGRATION_TABLES_V1 = Object.freeze({
 import { lstatSync as lstatSync11, readFileSync as readFileSync13, realpathSync as realpathSync11 } from "node:fs";
 import path22 from "node:path";
 var COMMUNITY_NATIVE_MIGRATION_POLICY_PATH = "apps/aops-server/scripts/community-migration-policy-v1.json";
+var COMMUNITY_NATIVE_PACKAGE_MIGRATION_POLICY_PATH = "scripts/community-migration-policy-v1.json";
 var MAX_POLICY_BYTES = 2 * 1024 * 1024;
 var INSTANCE_NAME2 = /^[a-z0-9](?:[a-z0-9-]{0,30}[a-z0-9])?$/;
 var UUID4 = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
@@ -87338,7 +87349,15 @@ function readCommunityNativeMigrationPolicy(sourceRoot) {
   if (path22.relative(resolvedRoot, canonicalRoot) !== "" || path22.relative(canonicalRoot, resolvedRoot) !== "") {
     throw new Error("community_native_migration_source_root_alias_refused");
   }
-  const policyPath = path22.resolve(canonicalRoot, ...COMMUNITY_NATIVE_MIGRATION_POLICY_PATH.split("/"));
+  const manifest = (() => {
+    try {
+      return JSON.parse(readFileSync13(path22.join(canonicalRoot, "package.json"), "utf8"));
+    } catch {
+      return {};
+    }
+  })();
+  const relativePolicyPath = manifest.name === "@aopslab/aops-server" ? COMMUNITY_NATIVE_PACKAGE_MIGRATION_POLICY_PATH : COMMUNITY_NATIVE_MIGRATION_POLICY_PATH;
+  const policyPath = path22.resolve(canonicalRoot, ...relativePolicyPath.split("/"));
   if (!isWithin4(canonicalRoot, policyPath)) throw new Error("community_native_migration_policy_path_escape");
   const stats = lstatSync11(policyPath);
   if (!stats.isFile() || stats.isSymbolicLink() || stats.size < 1 || stats.size > MAX_POLICY_BYTES) {
@@ -88749,6 +88768,7 @@ function inspectCommunityNativeApplicationRecoveryStatus(paths) {
 
 // apps/aops-cli/src/lib/community-native-lifecycle.ts
 var PUBLIC_ROOT_NAME = "aops-community-distribution";
+var PUBLIC_SERVER_PACKAGE_NAME = "@aopslab/aops-server";
 var PUBLIC_PACKAGE_MANAGER = /^pnpm@(11\.[0-9]+\.[0-9]+)$/;
 var RELEASE_VERSION4 = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z]+(?:\.[0-9A-Za-z]+)*)?(?:\+[0-9A-Za-z]+(?:\.[0-9A-Za-z]+)*)?$/;
 var INSTANCE_NAME4 = /^[a-z0-9](?:[a-z0-9-]{0,30}[a-z0-9])?$/;
@@ -88784,7 +88804,7 @@ var RUNTIME_INVENTORY_EXCLUDED_DIRECTORIES = /* @__PURE__ */ new Set([
   "coverage",
   "node_modules"
 ]);
-var REQUIRED_SOURCE_PATHS = Object.freeze([
+var CHECKOUT_REQUIRED_SOURCE_PATHS = Object.freeze([
   "apps/aops-cli/package.json",
   "apps/aops-cockpit-v2/package.json",
   "apps/aops-server/package.json",
@@ -88794,11 +88814,31 @@ var REQUIRED_SOURCE_PATHS = Object.freeze([
   "pnpm-lock.yaml",
   "pnpm-workspace.yaml"
 ]);
-var REQUIRED_BUILD_PATHS = Object.freeze({
+var CHECKOUT_BUILD_PATHS = Object.freeze({
   hostEntry: "apps/aops-server/scripts/community-host.mjs",
   handlerEntry: "apps/aops-server/build/handler.js",
   cockpitIndex: "apps/aops-cockpit-v2/dist/index.html"
 });
+var PACKAGE_REQUIRED_SOURCE_PATHS = Object.freeze([
+  "aops-server-runtime.json",
+  "community-postgres.json",
+  "npm-shrinkwrap.json",
+  "package.json",
+  "runtime/agentspace-host-adapter.mjs",
+  "runtime/agentspace-tooling.mjs",
+  "runtime/docman-host-adapter.mjs",
+  "runtime/docman-policy.mjs",
+  "runtime/docman-tooling.mjs",
+  "runtime/projectman-host-adapter.mjs",
+  "runtime/scope-context.mjs",
+  "scripts/community-host.mjs",
+  "scripts/community-migration-policy-v1.json"
+]);
+var PACKAGE_BUILD_PATHS = Object.freeze({
+  hostEntry: "scripts/community-host.mjs",
+  handlerEntry: "build/handler.js",
+  cockpitIndex: "cockpit/index.html"
+});
 function sha2566(content) {
   return `sha256:${createHash14("sha256").update(content).digest("hex")}`;
 }
@@ -89078,7 +89118,8 @@ function parseNativeState(value, paths) {
     input.build.runtimeInventorySha256,
     input.build.buildFingerprint
   ].every((item) => SHA2567.test(String(item))) || input.server.host !== "127.0.0.1" || !validPort(input.server.port)) throw new Error("community_native_state_schema_invalid");
-  if (!samePhysicalPath(input.build.hostEntry, path25.join(input.source.root, REQUIRED_BUILD_PATHS.hostEntry)) || !samePhysicalPath(input.build.handlerEntry, path25.join(input.source.root, REQUIRED_BUILD_PATHS.handlerEntry)) || !samePhysicalPath(input.build.cockpitIndex, path25.join(input.source.root, REQUIRED_BUILD_PATHS.cockpitIndex))) throw new Error("community_native_state_build_path_mismatch");
+  const layout = sourceLayout(input.source.root);
+  if (!samePhysicalPath(input.build.hostEntry, path25.join(input.source.root, layout.buildPaths.hostEntry)) || !samePhysicalPath(input.build.handlerEntry, path25.join(input.source.root, layout.buildPaths.handlerEntry)) || !samePhysicalPath(input.build.cockpitIndex, path25.join(input.source.root, layout.buildPaths.cockpitIndex))) throw new Error("community_native_state_build_path_mismatch");
   if (input.profile === "native-external-postgres") {
     exactKeys5(input.postgres, ["mode", "configRef", "tlsPolicy"], "community_native_state_postgres_invalid");
     if (input.postgres.mode !== "external" || !path25.isAbsolute(input.postgres.configRef) || !["disable", "require", "verify-full"].includes(input.postgres.tlsPolicy)) throw new Error("community_native_state_postgres_invalid");
@@ -89358,6 +89399,51 @@ function sourcePackage(root) {
     throw new Error("community_native_source_package_json_invalid");
   }
 }
+function sourceLayout(root, manifest = sourcePackage(root)) {
+  if (manifest.name === PUBLIC_ROOT_NAME && manifest.private === true && typeof manifest.version === "string" && RELEASE_VERSION4.test(manifest.version) && typeof manifest.packageManager === "string" && PUBLIC_PACKAGE_MANAGER.test(manifest.packageManager)) {
+    return {
+      kind: "checkout",
+      requiredSourcePaths: CHECKOUT_REQUIRED_SOURCE_PATHS,
+      lockfilePath: "pnpm-lock.yaml",
+      buildPaths: CHECKOUT_BUILD_PATHS
+    };
+  }
+  if (manifest.name === PUBLIC_SERVER_PACKAGE_NAME && manifest.private !== true && typeof manifest.version === "string" && RELEASE_VERSION4.test(manifest.version) && typeof manifest.packageManager === "string" && PUBLIC_PACKAGE_MANAGER.test(manifest.packageManager)) {
+    const markerPath = safeRegularFile(root, "aops-server-runtime.json");
+    let marker;
+    try {
+      marker = JSON.parse(readFileSync16(markerPath, "utf8"));
+    } catch {
+      throw new Error("community_native_server_package_marker_invalid");
+    }
+    if (marker.schemaVersion !== 1 || marker.kind !== "aops-server-npm-runtime" || marker.packageName !== manifest.name || marker.packageVersion !== manifest.version || marker.packageManager !== manifest.packageManager || !marker.source || typeof marker.source !== "object" || Object.keys(marker.source).sort().join(",") !== "commit,repository" || marker.source.repository !== "https://github.com/eeemzs/aops-community" || !/^[a-f0-9]{40}$/.test(String(marker.source.commit ?? "")) || JSON.stringify(marker.source) !== JSON.stringify(manifest.aopsSource) || Object.keys(marker).sort().join(",") !== "kind,packageManager,packageName,packageVersion,schemaVersion,source") throw new Error("community_native_server_package_marker_invalid");
+    return {
+      kind: "npm-package",
+      requiredSourcePaths: PACKAGE_REQUIRED_SOURCE_PATHS,
+      lockfilePath: "npm-shrinkwrap.json",
+      buildPaths: PACKAGE_BUILD_PATHS
+    };
+  }
+  throw new Error("community_native_public_source_required");
+}
+function isPackagedCommunityServerSource(source) {
+  return sourceLayout(source.root).kind === "npm-package";
+}
+function isCommunityNativeNpmPackageSource(sourceRoot) {
+  const resolved = path25.resolve(sourceRoot);
+  return sourceLayout(realpathSync14(resolved)).kind === "npm-package";
+}
+function resolveCommunityNativeDefaultSourceRoot(fallbackRoot = process.cwd(), moduleUrl = import.meta.url) {
+  try {
+    const require2 = createRequire3(moduleUrl);
+    const packageJsonPath = require2.resolve(`${PUBLIC_SERVER_PACKAGE_NAME}/package.json`);
+    const packageRoot = path25.dirname(packageJsonPath);
+    sourceLayout(packageRoot);
+    return packageRoot;
+  } catch {
+    return path25.resolve(fallbackRoot);
+  }
+}
 function inspectCommunityNativeSource(sourceRoot = process.cwd()) {
   const resolved = path25.resolve(sourceRoot);
   let rootStats;
@@ -89369,10 +89455,10 @@ function inspectCommunityNativeSource(sourceRoot = process.cwd()) {
   if (!rootStats.isDirectory() || rootStats.isSymbolicLink()) throw new Error("community_native_source_root_invalid");
   const root = realpathSync14(resolved);
   const manifest = sourcePackage(root);
-  if (manifest.name !== PUBLIC_ROOT_NAME || manifest.private !== true || typeof manifest.version !== "string" || !RELEASE_VERSION4.test(manifest.version) || typeof manifest.packageManager !== "string" || !PUBLIC_PACKAGE_MANAGER.test(manifest.packageManager)) throw new Error("community_native_public_checkout_required");
-  for (const relativePath3 of REQUIRED_SOURCE_PATHS) safeRegularFile(root, relativePath3);
+  const layout = sourceLayout(root, manifest);
+  for (const relativePath3 of layout.requiredSourcePaths) safeRegularFile(root, relativePath3);
   const packageSha256 = hashFile(path25.join(root, "package.json"));
-  const lockfileSha256 = hashFile(path25.join(root, "pnpm-lock.yaml"));
+  const lockfileSha256 = hashFile(path25.join(root, layout.lockfilePath));
   const postgresProfileSha256 = hashFile(path25.join(root, COMMUNITY_NATIVE_POSTGRES_CONTRACT_PATH));
   const sourceInventory = inventoryCommunityNativeTree(root, SOURCE_INVENTORY_EXCLUDED_DIRECTORIES);
   return {
@@ -89397,9 +89483,10 @@ function inspectCommunityNativeSource(sourceRoot = process.cwd()) {
 }
 function inspectCommunityNativeBuild(source, completedAt, currentSource = inspectCommunityNativeSource(source.root)) {
   if (currentSource.packageSha256 !== source.packageSha256 || currentSource.lockfileSha256 !== source.lockfileSha256 || currentSource.sourceFileCount !== source.sourceFileCount || currentSource.sourceInventorySha256 !== source.sourceInventorySha256 || currentSource.sourceFingerprint !== source.sourceFingerprint) throw new Error("community_native_source_changed_during_build");
-  const hostEntry = safeRegularFile(source.root, REQUIRED_BUILD_PATHS.hostEntry);
-  const handlerEntry = safeRegularFile(source.root, REQUIRED_BUILD_PATHS.handlerEntry);
-  const cockpitIndex = safeRegularFile(source.root, REQUIRED_BUILD_PATHS.cockpitIndex);
+  const layout = sourceLayout(source.root);
+  const hostEntry = safeRegularFile(source.root, layout.buildPaths.hostEntry);
+  const handlerEntry = safeRegularFile(source.root, layout.buildPaths.handlerEntry);
+  const cockpitIndex = safeRegularFile(source.root, layout.buildPaths.cockpitIndex);
   const hostEntrySha256 = hashFile(hostEntry);
   const handlerEntrySha256 = hashFile(handlerEntry);
   const cockpitIndexSha256 = hashFile(cockpitIndex);
@@ -90599,7 +90686,9 @@ async function setupCommunityNativeInstall(params) {
     }
     assertCommunityNativeApplicationCurrent(inspection.state);
   }
-  const source = inspectCommunityNativeSource(params.sourceRoot ?? process.cwd());
+  const source = inspectCommunityNativeSource(
+    params.sourceRoot ?? resolveCommunityNativeDefaultSourceRoot()
+  );
   let configRef;
   if (params.contract.profile === "native-external-postgres") {
     if (params.contract.postgres.mode !== "external" || !params.contract.postgres.configRef || !params.contract.postgres.tlsPolicy) throw new Error("community_native_external_postgres_contract_required");
@@ -90609,16 +90698,18 @@ async function setupCommunityNativeInstall(params) {
   } else if (params.contract.postgres.mode !== "container") {
     throw new Error("community_native_container_postgres_contract_required");
   }
-  await runBuildChecked(
-    runtime,
-    { ...buildCommunityPnpmInvocation(source.root, ["install", "--frozen-lockfile"], params.env), signal: params.signal },
-    "install"
-  );
-  await runBuildChecked(
-    runtime,
-    { ...buildCommunityPnpmInvocation(source.root, ["run", "build"], params.env), signal: params.signal },
-    "build"
-  );
+  if (!isPackagedCommunityServerSource(source)) {
+    await runBuildChecked(
+      runtime,
+      { ...buildCommunityPnpmInvocation(source.root, ["install", "--frozen-lockfile"], params.env), signal: params.signal },
+      "install"
+    );
+    await runBuildChecked(
+      runtime,
+      { ...buildCommunityPnpmInvocation(source.root, ["run", "build"], params.env), signal: params.signal },
+      "build"
+    );
+  }
   throwIfNativeAborted(params.signal);
   const updatedAt = now().toISOString();
   const build = inspectCommunityNativeBuild(source, updatedAt);
@@ -90766,16 +90857,18 @@ async function rollbackCommunityNativeApplication(params) {
     throw new Error("community_native_application_update_target_not_active");
   }
   const source = inspectCommunityNativeSource(params.sourceRoot);
-  await runBuildChecked(
-    runtime,
-    { ...buildCommunityPnpmInvocation(source.root, ["install", "--frozen-lockfile"], params.env), signal: params.signal },
-    "rollback_install"
-  );
-  await runBuildChecked(
-    runtime,
-    { ...buildCommunityPnpmInvocation(source.root, ["run", "build"], params.env), signal: params.signal },
-    "rollback_build"
-  );
+  if (!isPackagedCommunityServerSource(source)) {
+    await runBuildChecked(
+      runtime,
+      { ...buildCommunityPnpmInvocation(source.root, ["install", "--frozen-lockfile"], params.env), signal: params.signal },
+      "rollback_install"
+    );
+    await runBuildChecked(
+      runtime,
+      { ...buildCommunityPnpmInvocation(source.root, ["run", "build"], params.env), signal: params.signal },
+      "rollback_build"
+    );
+  }
   throwIfNativeAborted(params.signal);
   const updatedAt = now().toISOString();
   const build = inspectCommunityNativeBuild(source, updatedAt);
@@ -92180,7 +92273,7 @@ async function runCommunityServerSetup(options, dependencies = {}) {
       status: "community-server-setup-preview",
       mutationFree: true,
       contract,
-      next: contract.runtime === "native" ? "Re-run with --apply to install dependencies, build the public checkout, and start the loopback native host." : "Re-run with --apply to verify the signed release and start the OCI stack."
+      next: contract.runtime === "native" ? "Re-run with --apply to start the installed npm server package, or build an explicit public checkout supplied with --source-root." : "Re-run with --apply to verify the signed release and start the OCI stack."
     }, options.json, options);
     return;
   }
@@ -92549,6 +92642,50 @@ async function runCommunityServerStatus(options) {
   }
   if (result.exitCode !== 0) process.exitCode = 1;
 }
+async function runCommunityServerHealth(options) {
+  const native = inspectNativeFrom(options);
+  if (native.status === "installed" && native.state) {
+    const observed = await inspectCommunityNativeRuntime(installSelection2(options));
+    const healthy = observed.runtimeState === "running" && observed.health === "healthy";
+    writeResult({
+      status: healthy ? "healthy" : "unhealthy",
+      runtime: "native",
+      profile: native.state.profile,
+      instance: native.state.instanceName,
+      origin: `http://127.0.0.1:${native.state.server.port}`,
+      runtimeState: observed.runtimeState,
+      supervisor: observed.supervisorAlive,
+      host: observed.hostAlive,
+      health: observed.health,
+      identityBound: observed.identity !== null,
+      error: observed.reason ?? null
+    }, options.json);
+    if (!healthy) process.exitCode = 1;
+    return;
+  }
+  if (native.status !== "not-installed") {
+    throw new Error(`community_native_health_refused:${native.status}:${native.error ?? "run_doctor"}`);
+  }
+  const inspection = requireInstalled(options);
+  try {
+    const lifecycle = createCommunityDockerAdapter({ verifyRelease: async () => void 0 });
+    await lifecycle.health({ paths: inspection.paths, state: inspection.state });
+    writeResult({
+      status: "healthy",
+      runtime: "oci",
+      instance: inspection.state.instanceName,
+      releaseVersion: inspection.state.activeRelease.releaseVersion
+    }, options.json);
+  } catch (error) {
+    writeResult({
+      status: "unhealthy",
+      runtime: "oci",
+      instance: inspection.state.instanceName,
+      error: error instanceof Error ? error.message : String(error)
+    }, options.json);
+    process.exitCode = 1;
+  }
+}
 async function runCommunityServerMigrationPlan(options, dependencies = {}) {
   const runtime = resolveDependencies(dependencies);
   await withCommunityCommandAbortScope(runtime.commandAbortRuntime, async (signal) => {
@@ -93404,11 +93541,12 @@ function releaseOptions(command) {
 function makeCommunityServerCommand(identity2 = {}) {
   const dependencies = { cliVersion: identity2.cliVersion };
   const command = new Command("server").description("Configure and operate a named AOPS Community server instance");
-  common3(releaseOptions(command.command("setup").description("Configure, build, and start an explicit native or OCI setup profile"))).requiredOption("--runtime <native|oci>", "Application runtime; no implicit default").option("--postgres <external|container>", "PostgreSQL owner for --runtime native").option("--postgres-config <path>", "Explicit external PostgreSQL env-file override; default: ~/.aops/aops.server.env (or AOPS_CLI_CONFIG_PATH directory)").option("--postgres-tls <disable|require|verify-full>", "Explicit external PostgreSQL TLS policy").option("--source-root <path>", "Public aops-community checkout root; defaults to the current directory").option("--port <number>", "Host port", "5900").option("--foreground", "Keep the native server attached to this terminal").option("--detach", "Start the native server in the background (default)").option("--preview", "Validate and print the setup contract without mutation").option("--apply", "Apply the selected setup contract").action((options) => runCommunityServerSetup(options, dependencies));
-  common3(command.command("start").alias("up").description("Start the installed native source host or OCI stack")).option("--foreground", "Keep the native server attached to this terminal").option("--detach", "Start the native server in the background (default)").action((options) => runCommunityServerStart(options, dependencies));
+  common3(releaseOptions(command.command("setup").description("Configure and start an npm-package, source-checkout, or OCI server profile"))).requiredOption("--runtime <native|oci>", "Application runtime; no implicit default").option("--postgres <external|container>", "PostgreSQL owner for --runtime native").option("--postgres-config <path>", "Explicit external PostgreSQL env-file override; default: ~/.aops/aops.server.env (or AOPS_CLI_CONFIG_PATH directory)").option("--postgres-tls <disable|require|verify-full>", "Explicit external PostgreSQL TLS policy").option("--source-root <path>", "Optional public aops-community checkout root; defaults to the installed @aopslab/aops-server package").option("--port <number>", "Host port", "5900").option("--foreground", "Keep the native server attached to this terminal").option("--detach", "Start the native server in the background (default)").option("--preview", "Validate and print the setup contract without mutation").option("--apply", "Apply the selected setup contract").action((options) => runCommunityServerSetup(options, dependencies));
+  common3(command.command("start").alias("up").description("Start the installed native npm/source host or OCI stack")).option("--foreground", "Keep the native server attached to this terminal").option("--detach", "Start the native server in the background (default)").action((options) => runCommunityServerStart(options, dependencies));
   common3(command.command("stop").alias("down").description("Stop the server without deleting data")).action((options) => runCommunityServerStop(options, dependencies));
   common3(command.command("restart").description("Restart the installed server")).option("--foreground", "Keep the restarted native server attached to this terminal").option("--detach", "Restart the native server in the background (default)").action((options) => runCommunityServerRestart(options, dependencies));
   common3(command.command("status").description("Show install and runtime status")).action(runCommunityServerStatus);
+  common3(command.command("health").description("Check the installed server health without mutation")).action(runCommunityServerHealth);
   common3(command.command("migration-plan").description("Read the exact pending native database migration plan without mutation")).action((options) => runCommunityServerMigrationPlan(options, dependencies));
   common3(command.command("attest-external-snapshot").description("Bind an operator-owned external PostgreSQL snapshot to one exact migration plan")).requiredOption("--expected-plan-sha256 <digest>", "Exact raw plan SHA-256 returned by server migration-plan").requiredOption("--provider <name>", "External snapshot provider or platform").requiredOption("--snapshot-ref <reference>", "Immutable external snapshot reference").option("--snapshot-digest <sha256:digest>", "Optional immutable snapshot content digest").requiredOption("--attested-by <identity>", "Operator identity accepting external recovery ownership").requiredOption("--restore-instructions-ref <reference>", "Durable runbook or restore-instructions reference").option("--preview", "Validate and print the exact attestation without writing it").option("--apply", "Write the immutable plan-bound attestation").option("--confirm-external-recovery-owner", "Confirm that restore execution remains externally owned").action((options) => runCommunityServerAttestExternalSnapshot(options, dependencies));
   common3(command.command("logs").description("Show recent server logs")).option("--tail <number>", "Number of log lines", "100").action(runCommunityServerLogs);
@@ -95275,6 +95413,9 @@ var NativeRuntimeRoot = class {
     this.rootIdentitySha256 = rootIdentitySha256;
     this.run = run;
   }
+  id;
+  rootIdentitySha256;
+  run;
   async createDirectory(relativePath3) {
     await this.run(["runtime-mkdir", this.id, hexUtf8(relativePath3)]);
   }
@@ -97205,17 +97346,17 @@ var SETUP_PATHS = [
   {
     id: "native-external",
     number: "1",
-    title: "Native server with external PostgreSQL"
+    title: "Npm server with operator-owned PostgreSQL"
   },
   {
     id: "native-container",
     number: "2",
-    title: "Native server with managed PostgreSQL container"
+    title: "Source server with PostgreSQL container (deferred)"
   },
   {
     id: "oci-ready",
     number: "3",
-    title: "Ready OCI stack from published images"
+    title: "Ready OCI stack from published images (deferred)"
   },
   {
     id: "cli-existing",
@@ -97547,15 +97688,19 @@ async function inspectSetupReadiness(options = {}) {
   }
   const hasCommand = probes.commandAvailable ?? commandAvailable;
   if (selected === "native-external" || selected === "native-container") {
-    const selectedSourceRoot = path35.resolve(options.sourceRoot ?? native.state?.source.root ?? cwd);
+    const selectedSourceRoot = path35.resolve(
+      options.sourceRoot ?? native.state?.source.root ?? resolveCommunityNativeDefaultSourceRoot(cwd)
+    );
     let nativeSourceReady = false;
+    let npmPackage = false;
     let nativeSourceError = null;
     if (probes.commandAvailable) {
-      nativeSourceReady = hasCommand("pnpm");
+      nativeSourceReady = options.sourceRoot ? hasCommand("pnpm") : true;
     } else {
       try {
         inspectCommunityNativeSource(selectedSourceRoot);
-        buildCommunityPnpmInvocation(selectedSourceRoot, ["--version"], processEnv);
+        npmPackage = isCommunityNativeNpmPackageSource(selectedSourceRoot);
+        if (!npmPackage) buildCommunityPnpmInvocation(selectedSourceRoot, ["--version"], processEnv);
         nativeSourceReady = true;
       } catch (error) {
         nativeSourceError = safeReason(error, "community_native_source_runtime_invalid");
@@ -97568,11 +97713,12 @@ async function inspectSetupReadiness(options = {}) {
       id: "runtime",
       state: runtimeReady ? "ready" : "action-required",
       required: true,
-      summary: runtimeReady ? "Native source runtime requirements are available." : needsDocker ? "The native source checkout, pnpm 11 and a running Docker daemon are required." : "A valid Community source checkout and pnpm 11 are required.",
+      summary: runtimeReady ? npmPackage ? "The installed npm server runtime is ready; no source build is required." : "Native source runtime requirements are available." : needsDocker ? "The native source checkout, pnpm 11 and a running Docker daemon are required." : "Install @aopslab/aops-server through the CLI package, or provide a valid Community checkout with pnpm 11.",
       next: runtimeReady ? void 0 : "Use a Community source checkout and install its declared pnpm version and required container runtime.",
       data: {
         node: process.version,
         sourceRoot: selectedSourceRoot,
+        sourceKind: npmPackage ? "npm-package" : "source-checkout",
         nativeSource: nativeSourceReady,
         docker: needsDocker ? dockerReady : null,
         error: nativeSourceError
@@ -97729,7 +97875,7 @@ async function runSetupInitOrchestrator(options = {}, dependencies = {}) {
           name: `${entry.number}. ${entry.title}`,
           value: entry.id
         })),
-        default: "oci-ready"
+        default: "native-external"
       });
     }
   }
@@ -97790,9 +97936,10 @@ async function runSetupInitOrchestrator(options = {}, dependencies = {}) {
     throw new Error("setup_init_postgres_tls_required_for_path_1");
   }
   const localServerPath = selectedPath !== "cli-existing";
+  const catalogDeferredForNpm = selectedPath === "native-external" && !options.sourceRoot && !normalizeNonEmpty9(options.catalogRelease) && !normalizeNonEmpty9(options.agentAssetsRelease);
   let officialCatalogRelease;
   let officialCatalogReleaseSource;
-  if (localServerPath && !options.noCatalog && dependencies.officialCatalog) {
+  if (localServerPath && !options.noCatalog && !catalogDeferredForNpm && dependencies.officialCatalog) {
     const selectedRelease = options.catalogRelease ?? options.agentAssetsRelease;
     if (normalizeNonEmpty9(selectedRelease)) {
       officialCatalogRelease = resolveOfficialCatalogReleasePath(selectedRelease);
@@ -97885,6 +98032,14 @@ async function runSetupInitOrchestrator(options = {}, dependencies = {}) {
       coreClientAssetsAffected: false,
       existingCatalogRowsDeleted: false
     });
+  } else if (localServerPath && catalogDeferredForNpm) {
+    steps.push({
+      action: "setup.catalog.skip",
+      status: "skipped",
+      reason: "npm-runtime-has-no-signed-catalog-release",
+      coreClientAssetsAffected: false,
+      existingCatalogRowsDeleted: false
+    });
   } else if (localServerPath && dependencies.officialCatalog && officialCatalogRelease) {
     const catalog = await dependencies.officialCatalog.reconcile({
       fromRelease: officialCatalogRelease,
@@ -98345,27 +98500,28 @@ async function runCommunitySetupInit(options = {}) {
   });
 }
 function addSetupInitOptions(command) {
-  return command.option("--path <path>", "Setup path: 1 | 2 | 3 | 4 (semantic ids are also accepted)").option("--postgres-config <path>", "Explicit PostgreSQL env file override for path 1").option("--postgres-tls <policy>", "Path 1 TLS policy: disable | require | verify-full").option("--api-base-url <url>", "Local or existing-server API base URL without credentials").option("--instance <name>", "Local Community instance name").option("--data-root <path>", "Local Community data root override").option("--source-root <path>", "Native Community source checkout override for paths 1 and 2").option("--port <port>", "Local server port", (value) => Number.parseInt(String(value), 10)).option("--target-name <name>", "Persistent target name for path 4").option("--target-auth-provider <provider>", "Path 4 target auth: trusted-local | authv2-jwt-session").option("--target-tls-policy <policy>", "Path 4 target TLS: loopback-http | system-ca").option("--agent-assets <action>", "Global AOPS gateway action: status | install | repair | skip").option("--agent-assets-release <path>", "Verified release directory for --agent-assets install").option("--no-catalog", "Skip the default inert official server catalog import").option("--catalog-release <path>", "Explicit verified-release override (normally resolved from the Community install)").option("--catalog-idempotency-key <key>", "Explicit official catalog reconcile replay key").option("--apply", "Apply the selected path after readiness checks").option("--resume", "With --apply, resume the same idempotent setup orchestration").option("--timeout-ms <ms>", "Read-only host probe timeout", (value) => Number.parseInt(String(value), 10)).option("--yes", "Non-interactive; report missing selections as actions").option("--json", "Output one typed readiness or apply-result envelope");
+  return command.option("--path <path>", "Setup path: 1 | 2 | 3 | 4 (semantic ids are also accepted)").option("--postgres-config <path>", "Explicit PostgreSQL env file override for the default npm server path").option("--postgres-tls <policy>", "PostgreSQL TLS policy: disable | require | verify-full").option("--api-base-url <url>", "Local or existing-server API base URL without credentials").option("--instance <name>", "Local Community instance name").option("--data-root <path>", "Local Community data root override").option("--source-root <path>", "Optional native Community source checkout override; npm server package is the default").option("--port <port>", "Local server port", (value) => Number.parseInt(String(value), 10)).option("--target-name <name>", "Persistent target name for path 4").option("--target-auth-provider <provider>", "Path 4 target auth: trusted-local | authv2-jwt-session").option("--target-tls-policy <policy>", "Path 4 target TLS: loopback-http | system-ca").option("--agent-assets <action>", "Global AOPS gateway action: status | install | repair | skip").option("--agent-assets-release <path>", "Verified release directory for --agent-assets install").option("--no-catalog", "Skip the default inert official server catalog import").option("--catalog-release <path>", "Explicit verified-release override (normally resolved from the Community install)").option("--catalog-idempotency-key <key>", "Explicit official catalog reconcile replay key").option("--apply", "Apply the selected path after readiness checks").option("--resume", "With --apply, resume the same idempotent setup orchestration").option("--timeout-ms <ms>", "Read-only host probe timeout", (value) => Number.parseInt(String(value), 10)).option("--yes", "Non-interactive; report missing selections as actions").option("--json", "Output one typed readiness or apply-result envelope");
 }
 function makeCommunitySetupCommand() {
   const command = new Command("setup").description("Inspect and bootstrap an AOPS Community installation");
   command.addCommand(makeOfficialCatalogSetupCommand());
-  addSetupInitOptions(command.command("init").description("Guide paths 1, 2, 3, or 4; read-only unless --apply is supplied")).addHelpText("after", `
+  addSetupInitOptions(command.command("init").description("Guide npm-server, source, deferred Docker, or existing-server setup; read-only unless --apply is supplied")).addHelpText("after", `
 Examples:
   aops-cli setup init
   aops-cli setup init --path 1 --postgres-tls verify-full --json
-  aops-cli setup init --path 3 --apply --yes
   aops-cli setup init --path 4 --api-base-url https://aops.example.com --json
-  aops-cli setup init --path 2 --catalog-release <path> --apply --yes
-  aops-cli setup init --path 2 --no-catalog --apply --yes
+  aops-cli setup init --path 1 --no-catalog --apply --yes
 
 This command is distinct from repo-local \`aops-cli init\`.
-Path 1 uses \`~/.aops/aops.server.env\` by default, or the directory selected by
+Path 1 is the promoted npm-server path and uses \`~/.aops/aops.server.env\` by default, or the directory selected by
 \`AOPS_CLI_CONFIG_PATH\`. A relative \`AOPS_PG_SSL_ROOT_CERT\` is resolved beside
 the selected env file. \`--postgres-config\` remains an explicit override.
 Community agent assets use the TASK-136 \`aops-cli assets\` contract; the
 development-only repo-mirror installer is not part of this command.
-Fresh server setup imports only the inert signed official catalog by default.
+Source/release setup imports only the inert signed official catalog by default.
+The npm runtime skips that optional catalog unless \`--catalog-release\` is supplied.
+Docker-backed paths 2 and 3 are retained for later reactivation but are not the
+promoted installation path in this release.
 The CLI first resolves the canonical signed release from the selected source or
 installed Community runtime; \`--catalog-release\` is only an explicit override.
 \`--no-catalog\` is the bare/minimal opt-out; it never removes existing rows or
@@ -98375,7 +98531,7 @@ changes the offline client core. Reconcile and rollback remain explicit under
     const { catalog, ...options } = commandOptions2;
     await runCommunitySetupInit({ ...options, noCatalog: catalog === false });
   });
-  command.command("server-env").description("Create or validate the global trusted-local PostgreSQL env for path 1").option("--env-path <path>", "Explicit env file override (default: ~/.aops/aops.server.env)").option("--yes", "Non-interactive; read AOPS_PG_URL from the environment or existing file").option("--json", "Output a secret-free JSON summary").addHelpText("after", `
+  command.command("server-env").description("Create or validate the global trusted-local PostgreSQL env for the npm server").option("--env-path <path>", "Explicit env file override (default: ~/.aops/aops.server.env)").option("--yes", "Non-interactive; read AOPS_PG_URL from the environment or existing file").option("--json", "Output a secret-free JSON summary").addHelpText("after", `
 Examples:
   aops-cli setup server-env
   AOPS_PG_URL='<private-url>' aops-cli setup server-env --yes --json
@@ -102108,19 +102264,15 @@ var GUIDE_TARGETS = {
     mirrorPath: path47.join(".aops", "docman", "domain-guides", "agentspace-user-guide.md")
   },
   projectman: {
-    fallbackPath: "../../../../domains/projectman/USER_GUIDE.md",
     mirrorPath: path47.join(".aops", "docman", "domain-guides", "projectman-user-guide.md")
   },
   docman: {
-    fallbackPath: "../../../../domains/docman/USER_GUIDE.md",
     mirrorPath: path47.join(".aops", "docman", "domain-guides", "docman-user-guide.md")
   },
   fileman: {
-    fallbackPath: "../../../../domains/fileman/USER_GUIDE.md",
     mirrorPath: path47.join(".aops", "docman", "domain-guides", "fileman-user-guide.md")
   },
   tasker: {
-    fallbackPath: "../../../../domains/tasker/USER_GUIDE.md",
     mirrorPath: path47.join(".aops", "docman", "domain-guides", "tasker-user-guide.md")
   },
   agentAssets: {
@@ -123776,7 +123928,7 @@ function makeChatCommand() {
 // apps/aops-cli/src/commands/chatv3.ts
 import { readFileSync as readFileSync29 } from "node:fs";
 
-// domains/chatv3/chatv3-product-client/dist/crypto.js
+// node_modules/.pnpm/@aopslab+domain-product-client-chatv3@0.1.1_react@19.2.4/node_modules/@aopslab/domain-product-client-chatv3/dist/crypto.js
 var V0_CIPHER_SUITE = "v0-shared-epoch";
 var V0_KDF_META = {
   kdf: "hkdf-sha256",
@@ -123856,7 +124008,7 @@ async function decryptText(epochKey, envelope) {
   return decoder.decode(plaintext);
 }
 
-// domains/chatv3/chatv3-product-client/dist/invite.js
+// node_modules/.pnpm/@aopslab+domain-product-client-chatv3@0.1.1_react@19.2.4/node_modules/@aopslab/domain-product-client-chatv3/dist/invite.js
 function buildInvite(invite) {
   const base = encodeURIComponent(invite.serverBaseUrl);
   if (invite.mode === "server-encrypted") {
@@ -123898,7 +124050,7 @@ function parseInvite(value) {
   };
 }
 
-// domains/chatv3/chatv3-product-client/dist/keystore.js
+// node_modules/.pnpm/@aopslab+domain-product-client-chatv3@0.1.1_react@19.2.4/node_modules/@aopslab/domain-product-client-chatv3/dist/keystore.js
 var MemoryKeyStore = class {
   wrapSecrets = /* @__PURE__ */ new Map();
   epochKeys = /* @__PURE__ */ new Map();
@@ -123916,7 +124068,7 @@ var MemoryKeyStore = class {
   }
 };
 
-// domains/chatv3/light-client-core/dist/config.js
+// node_modules/.pnpm/@aopslab+light-client-core@0.1.1_react@19.2.4/node_modules/@aopslab/light-client-core/dist/config.js
 function normalizeBaseUrl2(value) {
   return value.replace(/\/$/, "");
 }
@@ -123924,7 +124076,7 @@ function bindFetch() {
   return globalThis.fetch.bind(globalThis);
 }
 
-// domains/chatv3/light-client-core/dist/token.js
+// node_modules/.pnpm/@aopslab+light-client-core@0.1.1_react@19.2.4/node_modules/@aopslab/light-client-core/dist/token.js
 var MemoryTokenProvider = class {
   token = null;
   constructor(initial) {
@@ -123941,7 +124093,7 @@ var MemoryTokenProvider = class {
   }
 };
 
-// domains/chatv3/light-client-core/dist/http.js
+// node_modules/.pnpm/@aopslab+light-client-core@0.1.1_react@19.2.4/node_modules/@aopslab/light-client-core/dist/http.js
 function makeError(status, code, message) {
   const err = new Error(message);
   err.status = status;
@@ -124003,13 +124155,13 @@ var EnvelopeHttp = class {
   }
 };
 
-// domains/chatv3/light-client-core/dist/stream/index.js
+// node_modules/.pnpm/@aopslab+light-client-core@0.1.1_react@19.2.4/node_modules/@aopslab/light-client-core/dist/stream/index.js
 function appendQueryParam(url, key, value) {
   const sep = url.includes("?") ? "&" : "?";
   return `${url}${sep}${encodeURIComponent(key)}=${encodeURIComponent(value)}`;
 }
 
-// domains/chatv3/chatv3-product-client/dist/http.js
+// node_modules/.pnpm/@aopslab+domain-product-client-chatv3@0.1.1_react@19.2.4/node_modules/@aopslab/domain-product-client-chatv3/dist/http.js
 var Chatv3Http = class extends EnvelopeHttp {
   memberHeaders;
   authv2AccessToken;
@@ -124071,7 +124223,7 @@ var Chatv3Http = class extends EnvelopeHttp {
   }
 };
 
-// domains/chatv3/chatv3-product-client/dist/client.js
+// node_modules/.pnpm/@aopslab+domain-product-client-chatv3@0.1.1_react@19.2.4/node_modules/@aopslab/domain-product-client-chatv3/dist/client.js
 var Chatv3Client = class {
   http;
   keyStore;

package/dist/community-native-child.js

@@ -0,0 +1,223 @@
+// apps/aops-cli/src/lib/community-native-child.ts
+import { randomBytes } from "node:crypto";
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+var COMMUNITY_NATIVE_CHILD_PROTOCOL = "aops-community-native-child-v1";
+var COMMUNITY_NATIVE_CONTROL_PROTOCOL = "aops-community-native-control-v1";
+var UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+var SHA256 = /^sha256:[a-f0-9]{64}$/;
+var HOST_STOP_GRACE_MS = 2e3;
+function requiredEnv(env, key) {
+  const value = String(env[key] ?? "").trim();
+  if (!value) throw new Error(`community_native_child_env_required:${key}`);
+  return value;
+}
+function parsePort(value) {
+  if (!/^[1-9]\d{0,4}$/.test(value) || Number(value) > 65535) {
+    throw new Error("community_native_child_port_invalid");
+  }
+  return Number(value);
+}
+function atomicJsonWrite(targetPath, value) {
+  const parent = path.dirname(targetPath);
+  if (!existsSync(parent)) throw new Error("community_native_child_identity_parent_missing");
+  const tempPath = path.join(parent, `.${path.basename(targetPath)}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`);
+  try {
+    writeFileSync(tempPath, `${JSON.stringify(value, null, 2)}
+`, { encoding: "utf8", flag: "wx", mode: 384 });
+    renameSync(tempPath, targetPath);
+  } finally {
+    rmSync(tempPath, { force: true });
+  }
+}
+function buildCommunityNativeChildIdentity(env = process.env, pid = process.pid, hostPid = pid) {
+  const launchId = requiredEnv(env, "AOPS_NATIVE_LAUNCH_ID");
+  const startedAt = requiredEnv(env, "AOPS_NATIVE_STARTED_AT");
+  const sourceFingerprint = requiredEnv(env, "AOPS_NATIVE_SOURCE_FINGERPRINT");
+  const hostEntry = path.resolve(requiredEnv(env, "AOPS_NATIVE_HOST_ENTRY"));
+  const controlPathInput = requiredEnv(env, "AOPS_NATIVE_CONTROL_PATH");
+  if (!path.isAbsolute(controlPathInput)) throw new Error("community_native_child_control_path_invalid");
+  const controlPath = path.resolve(controlPathInput);
+  if (!UUID.test(launchId)) throw new Error("community_native_child_launch_id_invalid");
+  if (!Number.isSafeInteger(pid) || pid < 1 || !Number.isSafeInteger(hostPid) || hostPid < 1) {
+    throw new Error("community_native_child_pid_invalid");
+  }
+  if (Number.isNaN(Date.parse(startedAt))) throw new Error("community_native_child_started_at_invalid");
+  if (!SHA256.test(sourceFingerprint)) throw new Error("community_native_child_source_fingerprint_invalid");
+  if (!path.isAbsolute(hostEntry)) throw new Error("community_native_child_host_entry_invalid");
+  return {
+    schemaVersion: 1,
+    protocol: COMMUNITY_NATIVE_CHILD_PROTOCOL,
+    launchId,
+    pid,
+    hostPid,
+    startedAt,
+    sourceFingerprint,
+    hostEntry,
+    controlPath,
+    port: parsePort(requiredEnv(env, "AOPS_NATIVE_PORT"))
+  };
+}
+function removeIdentityIfOwned(identityPath, launchId) {
+  try {
+    const parsed = JSON.parse(readFileSync(identityPath, "utf8"));
+    if (parsed.protocol === COMMUNITY_NATIVE_CHILD_PROTOCOL && parsed.launchId === launchId) {
+      rmSync(identityPath, { force: true });
+    }
+  } catch {
+  }
+}
+function readOwnedStopRequest(controlPath, launchId) {
+  try {
+    const parsed = JSON.parse(readFileSync(controlPath, "utf8"));
+    if (parsed.schemaVersion !== 1 || parsed.protocol !== COMMUNITY_NATIVE_CONTROL_PROTOCOL || parsed.launchId !== launchId || parsed.command !== "stop" || Number.isNaN(Date.parse(String(parsed.requestedAt))) || Object.keys(parsed).sort().join(",") !== "command,launchId,protocol,requestedAt,schemaVersion") return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+function removeControlIfOwned(controlPath, launchId) {
+  if (readOwnedStopRequest(controlPath, launchId)) rmSync(controlPath, { force: true });
+}
+function spawnCommunityNativeHost(hostEntry, env) {
+  return spawn(process.execPath, [hostEntry], {
+    cwd: process.cwd(),
+    env,
+    detached: false,
+    windowsHide: true,
+    stdio: "inherit"
+  });
+}
+async function waitForHostSpawn(host) {
+  await new Promise((resolve, reject) => {
+    const onSpawn = () => {
+      host.off("error", onError);
+      resolve();
+    };
+    const onError = (error) => {
+      host.off("spawn", onSpawn);
+      reject(error);
+    };
+    host.once("spawn", onSpawn);
+    host.once("error", onError);
+  });
+}
+function observeHostOutcome(host) {
+  if (host.exitCode !== null || host.signalCode !== null) {
+    return Promise.resolve({
+      kind: "exit",
+      value: { exitCode: host.exitCode, signal: host.signalCode }
+    });
+  }
+  return new Promise((resolve) => {
+    const onExit = (exitCode, signal) => {
+      host.off("error", onError);
+      resolve({ kind: "exit", value: { exitCode, signal } });
+    };
+    const onError = (error) => {
+      host.off("exit", onExit);
+      resolve({ kind: "error", error });
+    };
+    host.once("exit", onExit);
+    host.once("error", onError);
+  });
+}
+async function terminateAndReapHost(host) {
+  if (host.exitCode !== null || host.signalCode !== null) return;
+  const exited = new Promise((resolve) => {
+    host.once("exit", () => resolve());
+  });
+  host.kill("SIGKILL");
+  await exited;
+}
+async function runCommunityNativeChild(env = process.env, runtime = {}) {
+  const identityPathInput = requiredEnv(env, "AOPS_NATIVE_IDENTITY_PATH");
+  if (!path.isAbsolute(identityPathInput)) throw new Error("community_native_child_identity_path_invalid");
+  const identityPath = path.resolve(identityPathInput);
+  const controlPathInput = requiredEnv(env, "AOPS_NATIVE_CONTROL_PATH");
+  if (!path.isAbsolute(controlPathInput)) throw new Error("community_native_child_control_path_invalid");
+  const controlPath = path.resolve(controlPathInput);
+  const hostEntry = path.resolve(requiredEnv(env, "AOPS_NATIVE_HOST_ENTRY"));
+  if (!existsSync(hostEntry)) throw new Error("community_native_child_host_entry_missing");
+  mkdirSync(path.dirname(identityPath), { recursive: true, mode: 448 });
+  const host = (runtime.spawnHost ?? spawnCommunityNativeHost)(hostEntry, env);
+  await waitForHostSpawn(host);
+  const hostOutcome = observeHostOutcome(host);
+  let cleanup;
+  let controlTimer;
+  let forceStopTimer;
+  let stopping = false;
+  const forward = (signal) => {
+    if (stopping) return;
+    stopping = true;
+    try {
+      host.kill(signal);
+    } catch {
+    }
+    forceStopTimer = setTimeout(() => {
+      if (host.exitCode === null && host.signalCode === null) {
+        try {
+          host.kill("SIGKILL");
+        } catch {
+        }
+      }
+    }, HOST_STOP_GRACE_MS);
+    forceStopTimer.unref();
+  };
+  const onSigint = () => forward("SIGINT");
+  const onSigterm = () => forward("SIGTERM");
+  try {
+    if (!host.pid) throw new Error("community_native_child_host_pid_missing");
+    const identity = buildCommunityNativeChildIdentity(env, process.pid, host.pid);
+    atomicJsonWrite(identityPath, identity);
+    cleanup = () => {
+      removeIdentityIfOwned(identityPath, identity.launchId);
+      removeControlIfOwned(controlPath, identity.launchId);
+    };
+    process.once("exit", cleanup);
+    process.once("SIGINT", onSigint);
+    process.once("SIGTERM", onSigterm);
+    controlTimer = setInterval(() => {
+      if (readOwnedStopRequest(controlPath, identity.launchId)) {
+        removeControlIfOwned(controlPath, identity.launchId);
+        forward("SIGTERM");
+      }
+    }, 100);
+    const outcome = await hostOutcome;
+    if (outcome.kind === "error") throw outcome.error;
+    if (!stopping && outcome.value.exitCode !== 0) {
+      throw new Error(
+        `community_native_child_host_failed:${outcome.value.exitCode ?? outcome.value.signal ?? "unknown"}`
+      );
+    }
+  } catch (error) {
+    await terminateAndReapHost(host);
+    throw error;
+  } finally {
+    process.off("SIGINT", onSigint);
+    process.off("SIGTERM", onSigterm);
+    if (cleanup) process.off("exit", cleanup);
+    if (controlTimer) clearInterval(controlTimer);
+    if (forceStopTimer) clearTimeout(forceStopTimer);
+    cleanup?.();
+  }
+}
+function isCommunityNativeChildEntry(moduleUrl = import.meta.url, argvPath = process.argv[1]) {
+  return typeof argvPath === "string" && /^community-native-child\.[cm]?[jt]s$/i.test(path.basename(argvPath)) && moduleUrl === pathToFileURL(argvPath).href;
+}
+if (isCommunityNativeChildEntry()) {
+  runCommunityNativeChild().catch((error) => {
+    process.stderr.write(`[aops-community] native child failed: ${error instanceof Error ? error.message : String(error)}
+`);
+    process.exitCode = 1;
+  });
+}
+export {
+  COMMUNITY_NATIVE_CHILD_PROTOCOL,
+  COMMUNITY_NATIVE_CONTROL_PROTOCOL,
+  buildCommunityNativeChildIdentity,
+  isCommunityNativeChildEntry,
+  runCommunityNativeChild
+};

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@aopslab/aops-cli",
-  "version": "0.1.1",
-  "type": "module",
+  "version": "0.1.3",
   "description": "AOPS Community operator CLI.",
   "license": "Apache-2.0",
+  "type": "module",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/eeemzs/aops-community.git",
@@ -27,10 +27,16 @@
   "engines": {
     "node": ">=22.9.0"
   },
+  "packageManager": "pnpm@11.9.0",
+  "aopsSource": {
+    "repository": "https://github.com/eeemzs/aops-community",
+    "commit": "c04eead7a23aee089eab02942764b0672fc41d71"
+  },
+  "dependencies": {
+    "@aopslab/aops-server": "0.1.0"
+  },
   "publishConfig": {
     "access": "public",
-    "registry": "https://registry.npmjs.org/",
-    "provenance": true,
-    "tag": "latest"
+    "registry": "https://registry.npmjs.org"
   }
 }