@volcengine/tls-observer-pi-install 0.0.1

package/src/installer/installer-runner.ts

@@ -0,0 +1,808 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { execFile, execFileSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { pathToFileURL } from 'node:url';
+import { promisify } from 'node:util';
+import readline from 'node:readline/promises';
+import { randomInt } from 'node:crypto';
+
+type AnyRecord = Record<string, any>;
+
+type TlsServiceClient = {
+  isAkSk: boolean;
+  DescribeProjects: (payload: AnyRecord) => Promise<AnyRecord>;
+  CreateProject: (payload: AnyRecord) => Promise<AnyRecord>;
+  DescribeApps: (payload: AnyRecord) => Promise<AnyRecord>;
+  CreateApp: (payload: AnyRecord) => Promise<AnyRecord>;
+  DescribeLogApps: (payload: AnyRecord) => Promise<AnyRecord>;
+  DescribeTemplates: (payload: AnyRecord) => Promise<AnyRecord>;
+};
+
+type OpenapiModule = {
+  tlsOpenapi?: {
+    TlsService?: new (options: AnyRecord) => AnyRecord;
+  };
+};
+
+type InstallOptions = {
+  help: boolean;
+  nonInteractive: boolean;
+  force: boolean;
+  beta: boolean;
+  dryRun: boolean;
+  skipTlsConfig: boolean;
+  piBin: string;
+  registry: string;
+  pluginPackage: string;
+  pluginVersion?: string;
+  envTarget: string;
+  dataRoot: string;
+  region?: string;
+  traceTopicId?: string;
+  apiKey?: string;
+  ak?: string;
+  sk?: string;
+  authMode: string;
+  exportTimeoutMs: string;
+  captureContent: string;
+  tlsEndpoint?: string;
+  projectId?: string;
+  projectName?: string;
+  logAppId?: string;
+  logAppName?: string;
+  logAppType: string;
+  templateName: string;
+  templateId?: string;
+};
+
+type PluginInstallResult = {
+  source: string;
+  target: string;
+  packageSpec?: string;
+  version?: string;
+  dryRun?: boolean;
+};
+
+const execFileAsync = promisify(execFile);
+const PLUGIN_PACKAGE_NAME = '@volcengine/tls-observer-pi';
+const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
+const DEFAULT_ENV_TARGET = path.join(homedir(), '.pi', 'agent', 'tls-observer-pi.env');
+const DEFAULT_DATA_ROOT = path.join(homedir(), '.pi', 'agent', 'tls-observer-pi');
+const DEFAULT_REGION = 'cn-beijing';
+const DEFAULT_PROJECT_NAME = 'pi_observability';
+const DEFAULT_APP_NAME_PREFIX = 'pi-observability';
+const DEFAULT_TLS_ENDPOINT = 'tls-cn-beijing.volces.com';
+const DEFAULT_LOG_APP_TYPE = 'Pi';
+const DEFAULT_TEMPLATE_NAME = 'Pi';
+const LOCAL_PLUGIN_SOURCE_ENV_KEYS = [
+  'PI_PLUGIN_SOURCE',
+  'PI_TLS_PLUGIN_SOURCE',
+  'TRAE_TLS_PLUGIN_SOURCE',
+] as const;
+
+function readEnvString(key: string): string | undefined {
+  const value = process.env[key];
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+
+function readEnvBool(key: string): boolean {
+  const value = readEnvString(key);
+  return value ? /^(1|true|yes|y|on)$/i.test(value) : false;
+}
+
+function takeArg(argv: string[], index: number, flag: string): string {
+  const value = argv[index + 1];
+  if (typeof value !== 'string' || value.startsWith('--')) {
+    throw new Error(`${flag} requires a value`);
+  }
+  return value;
+}
+
+function defaultTlsEndpointForRegion(region?: string): string {
+  return region ? `tls-${region}.volces.com` : DEFAULT_TLS_ENDPOINT;
+}
+
+function randomSuffix(): string {
+  const alphabet = '0123456789abcdefghijklmnopqrstuvwxyz';
+  let value = '';
+  for (let index = 0; index < 8; index += 1) value += alphabet[randomInt(alphabet.length)];
+  return value;
+}
+
+function defaultAppName(): string {
+  return `${DEFAULT_APP_NAME_PREFIX}_${randomSuffix()}`;
+}
+
+function applyDerivedDefaults(options: InstallOptions): void {
+  if (options.region && !options.tlsEndpoint) {
+    options.tlsEndpoint = defaultTlsEndpointForRegion(options.region);
+  }
+  if (!options.projectName && !options.projectId) options.projectName = DEFAULT_PROJECT_NAME;
+  if (!options.logAppName) options.logAppName = defaultAppName();
+}
+
+function parseCliOptions(argv: string[] = process.argv.slice(2)): InstallOptions {
+  const options = {
+    help: false,
+    nonInteractive: readEnvBool('PI_TLS_INSTALL_NON_INTERACTIVE'),
+    force: readEnvBool('PI_TLS_INSTALL_FORCE'),
+    beta: readEnvBool('PI_TLS_INSTALL_BETA'),
+    dryRun: readEnvBool('PI_TLS_INSTALL_DRY_RUN'),
+    skipTlsConfig: readEnvBool('PI_TLS_INSTALL_SKIP_TLS_CONFIG'),
+    piBin: readEnvString('PI_TLS_PI_BIN') || readEnvString('PI_BIN') || 'pi',
+    registry:
+      readEnvString('PI_TLS_NPM_REGISTRY') ||
+      readEnvString('npm_config_registry') ||
+      readEnvString('NPM_CONFIG_REGISTRY') ||
+      DEFAULT_REGISTRY,
+    pluginPackage: readEnvString('PI_TLS_PLUGIN_PACKAGE') || PLUGIN_PACKAGE_NAME,
+    pluginVersion: readEnvString('PI_TLS_PLUGIN_VERSION'),
+    envTarget: readEnvString('PI_TLS_ENV_TARGET') || DEFAULT_ENV_TARGET,
+    dataRoot: readEnvString('PI_TLS_DATA_ROOT') || DEFAULT_DATA_ROOT,
+    region: readEnvString('PI_TLS_REGION') || DEFAULT_REGION,
+    traceTopicId: readEnvString('PI_TLS_TRACE_TOPIC_ID'),
+    apiKey: readEnvString('PI_TLS_API_KEY'),
+    ak: readEnvString('PI_TLS_AK'),
+    sk: readEnvString('PI_TLS_SK'),
+    authMode: readEnvString('PI_TLS_AUTH_MODE') || 'header',
+    exportTimeoutMs: readEnvString('PI_TLS_EXPORT_TIMEOUT_MS') || '20000',
+    captureContent: readEnvString('PI_TLS_CAPTURE_CONTENT') || '1',
+    tlsEndpoint: readEnvString('PI_TLS_ENDPOINT'),
+    projectId: readEnvString('PI_TLS_PROJECT_ID'),
+    projectName: readEnvString('PI_TLS_PROJECT_NAME'),
+    logAppId: readEnvString('PI_TLS_LOG_APP_ID'),
+    logAppName: readEnvString('PI_TLS_LOG_APP_NAME'),
+    logAppType: readEnvString('PI_TLS_LOG_APP_TYPE') || DEFAULT_LOG_APP_TYPE,
+    templateName: readEnvString('PI_TLS_TEMPLATE_NAME') || DEFAULT_TEMPLATE_NAME,
+    templateId: readEnvString('PI_TLS_TEMPLATE_ID'),
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const current = argv[index];
+    if (current === '--help' || current === '-h') options.help = true;
+    else if (current === '--non-interactive') options.nonInteractive = true;
+    else if (current === '--force') options.force = true;
+    else if (current === '--beta') options.beta = true;
+    else if (current === '--dry-run') options.dryRun = true;
+    else if (current === '--skip-tls-config') options.skipTlsConfig = true;
+    else if (current === '--pi-bin') options.piBin = takeArg(argv, index++, current);
+    else if (current === '--registry') options.registry = takeArg(argv, index++, current);
+    else if (current === '--plugin-package') options.pluginPackage = takeArg(argv, index++, current);
+    else if (current === '--plugin-version') options.pluginVersion = takeArg(argv, index++, current);
+    else if (current === '--env-target') options.envTarget = takeArg(argv, index++, current);
+    else if (current === '--data-root') options.dataRoot = takeArg(argv, index++, current);
+    else if (current === '--region') options.region = takeArg(argv, index++, current);
+    else if (current === '--trace-topic-id') options.traceTopicId = takeArg(argv, index++, current);
+    else if (current === '--api-key') options.apiKey = takeArg(argv, index++, current);
+    else if (current === '--ak') options.ak = takeArg(argv, index++, current);
+    else if (current === '--sk') options.sk = takeArg(argv, index++, current);
+    else if (current === '--auth-mode') options.authMode = takeArg(argv, index++, current);
+    else if (current === '--export-timeout-ms') options.exportTimeoutMs = takeArg(argv, index++, current);
+    else if (current === '--capture-content') options.captureContent = takeArg(argv, index++, current);
+    else if (current === '--tls-endpoint') options.tlsEndpoint = takeArg(argv, index++, current);
+    else if (current === '--project-id') options.projectId = takeArg(argv, index++, current);
+    else if (current === '--project-name') options.projectName = takeArg(argv, index++, current);
+    else if (current === '--app-name' || current === '--log-app-name')
+      options.logAppName = takeArg(argv, index++, current);
+    else if (current === '--log-app-id') options.logAppId = takeArg(argv, index++, current);
+    else if (current === '--log-app-type') options.logAppType = takeArg(argv, index++, current);
+    else if (current === '--template-name') options.templateName = takeArg(argv, index++, current);
+    else if (current === '--template-id') options.templateId = takeArg(argv, index++, current);
+    else throw new Error(`Unknown option: ${current}`);
+  }
+
+  return options;
+}
+
+function printHelp(): void {
+  console.log(`TLS Observer Pi installer
+
+Usage:
+  tls-observer-pi-install [options]
+  npm exec -y --package=@volcengine/tls-observer-pi-install -- tls-observer-pi-install [options]
+
+Options:
+  --non-interactive              Read required inputs from flags/env
+  --force                        Overwrite existing env file
+  --beta                         Install @volcengine/tls-observer-pi@beta instead of @latest
+  --dry-run                      Write env but skip running pi install
+  --skip-tls-config              Install plugin without writing TLS env
+  --pi-bin <path>                Pi CLI executable. Default: pi
+  --registry <url>               NPM registry for plugin package. Default: https://registry.npmjs.org
+  --plugin-version <version>     Exact plugin version or dist-tag. Overrides --beta
+  --region <region>              TLS region. Default: cn-beijing
+  --tls-endpoint <host>          TLS Producer endpoint. Derived from region by default
+  --trace-topic-id <id>          TLS trace topic ID
+  --api-key <value>              TLS API Key
+  --ak <value>                   TLS Access Key
+  --sk <value>                   TLS Secret Key
+  --project-name <name>          TLS Project name for AK/SK auto creation
+  --app-name <name>              TLS LogApp name for AK/SK auto creation
+  --export-timeout-ms <ms>       TLS export timeout. Default: 20000
+  --capture-content <0|1>        Default: 1
+  --env-target <path>            Default: ~/.pi/agent/tls-observer-pi.env
+  --data-root <path>             Default: ~/.pi/agent/tls-observer-pi
+
+Environment:
+  PI_PLUGIN_SOURCE                Install a local built plugin package instead of installing from npm
+  PI_TLS_PI_BIN                   Pi CLI executable path when pi is not on PATH
+`);
+}
+
+function createReadline(): readline.Interface {
+  return readline.createInterface({ input: process.stdin, output: process.stdout, terminal: false });
+}
+
+async function promptText(rl: readline.Interface, message: string, defaultValue = ''): Promise<string> {
+  const suffix = defaultValue ? `\n    default: ${defaultValue}\n> ` : '\n> ';
+  const answer = await rl.question(`${message}${suffix}`);
+  return answer.trim() || defaultValue;
+}
+
+async function promptRequired(rl: readline.Interface, message: string, defaultValue = ''): Promise<string> {
+  while (true) {
+    const value = await promptText(rl, message, defaultValue);
+    if (value.trim()) return value.trim();
+    console.log('This value is required.');
+  }
+}
+
+function setTerminalEcho(enabled: boolean): boolean {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) return false;
+  try {
+    execFileSync('stty', [enabled ? 'echo' : '-echo'], {
+      stdio: ['inherit', 'ignore', 'ignore'],
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function promptSecret(rl: readline.Interface, message: string, defaultValue = ''): Promise<string> {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    return promptRequired(rl, message, defaultValue);
+  }
+
+  rl.pause();
+  return new Promise<string>((resolve, reject) => {
+    const input = process.stdin;
+    let value = '';
+    let finished = false;
+    const previousRawMode = input.isRaw;
+    let echoDisabled = false;
+    const suffix = defaultValue ? '\n    default: 已设置，回车保留\n> ' : '\n> ';
+
+    function cleanup(): void {
+      input.off('data', onData);
+      input.setRawMode(Boolean(previousRawMode));
+      if (echoDisabled) setTerminalEcho(true);
+      input.pause();
+      rl.resume();
+    }
+
+    function finish(): void {
+      if (finished) return;
+      finished = true;
+      cleanup();
+      process.stdout.write('\n');
+      const resolvedValue = value.trim() || defaultValue;
+      if (resolvedValue) {
+        resolve(resolvedValue);
+      } else {
+        console.log('This value is required.');
+        resolve(promptSecret(rl, message, defaultValue));
+      }
+    }
+
+    function onData(buffer: Buffer): void {
+      for (const char of buffer.toString('utf8')) {
+        if (finished) return;
+        if (char === '\u0003') {
+          finished = true;
+          cleanup();
+          reject(new Error('Interrupted'));
+          return;
+        }
+        if (char === '\r' || char === '\n') {
+          finish();
+          return;
+        }
+        if (char === '\u007f' || char === '\b') {
+          if (value.length > 0) {
+            value = [...value].slice(0, -1).join('');
+            process.stdout.write('\b \b');
+          }
+          continue;
+        }
+        value += char;
+        process.stdout.write('*');
+      }
+    }
+
+    input.resume();
+    input.setRawMode(true);
+    input.on('data', onData);
+    echoDisabled = setTerminalEcho(false);
+    process.stdout.write(`${message}${suffix}`);
+  });
+}
+
+function detectAuthType(options: InstallOptions): 'apiKey' | 'aksk' | undefined {
+  if (options.apiKey) return 'apiKey';
+  if (options.ak || options.sk) return 'aksk';
+  return undefined;
+}
+
+function validateBaseTlsConfig(options: InstallOptions): void {
+  const missing: string[] = [];
+  if (!options.region) missing.push('--region or PI_TLS_REGION');
+  const authType = detectAuthType(options);
+  if (!authType) missing.push('--api-key or --ak/--sk');
+  if (authType === 'apiKey' && (options.ak || options.sk)) {
+    throw new Error('API Key and AK/SK cannot be used together');
+  }
+  if (authType === 'aksk' && (!options.ak || !options.sk)) missing.push('--ak and --sk');
+  if (missing.length > 0) throw new Error(`Missing required TLS config: ${missing.join(', ')}`);
+}
+
+function validateTlsConfig(options: InstallOptions): void {
+  validateBaseTlsConfig(options);
+  const missing: string[] = [];
+  if (!options.tlsEndpoint) missing.push('--tls-endpoint or --region');
+  if (!options.traceTopicId) missing.push('--trace-topic-id or PI_TLS_TRACE_TOPIC_ID');
+  if (missing.length > 0) throw new Error(`Missing required TLS config: ${missing.join(', ')}`);
+}
+
+async function collectInteractiveOptions(options: InstallOptions): Promise<InstallOptions> {
+  if (options.nonInteractive) {
+    if (!options.skipTlsConfig) {
+      applyDerivedDefaults(options);
+      validateBaseTlsConfig(options);
+    }
+    return options;
+  }
+
+  const rl = createReadline();
+  try {
+    console.log('TLS Observer Pi installer');
+    options.force = true;
+    if (!options.skipTlsConfig) {
+      options.region = await promptRequired(rl, 'TLS region', options.region || DEFAULT_REGION);
+      applyDerivedDefaults(options);
+      const authType = await promptRequired(
+        rl,
+        'Auth type, apiKey or aksk',
+        detectAuthType(options) || 'apiKey',
+      );
+      if (authType === 'apiKey') {
+        options.traceTopicId = await promptRequired(rl, 'Trace topic ID', options.traceTopicId || '');
+        options.apiKey = await promptSecret(rl, 'TLS API Key', options.apiKey || '');
+        options.ak = undefined;
+        options.sk = undefined;
+      } else if (authType === 'aksk') {
+        options.projectName = await promptRequired(
+          rl,
+          'TLS Project name',
+          options.projectName || DEFAULT_PROJECT_NAME,
+        );
+        options.logAppName = await promptRequired(
+          rl,
+          'TLS LogApp name',
+          options.logAppName || defaultAppName(),
+        );
+        options.ak = await promptSecret(rl, 'TLS AK', options.ak || '');
+        options.sk = await promptSecret(rl, 'TLS SK', options.sk || '');
+        options.apiKey = undefined;
+      } else {
+        throw new Error('Auth type must be apiKey or aksk');
+      }
+    }
+    return options;
+  } finally {
+    rl.close();
+  }
+}
+
+function moduleSpecifier(specifier: string): string {
+  if (specifier.startsWith('.') || specifier.startsWith('/') || /^[A-Za-z]:[\\/]/.test(specifier)) {
+    return pathToFileURL(path.resolve(specifier)).href;
+  }
+  return specifier;
+}
+
+async function loadOpenapiModule(): Promise<OpenapiModule> {
+  return import(moduleSpecifier(readEnvString('PI_TLS_OPENAPI_MODULE') || '@volcengine/openapi'));
+}
+
+function createTlsService(options: InstallOptions, openapiModule: OpenapiModule): TlsServiceClient {
+  if (!openapiModule?.tlsOpenapi?.TlsService) {
+    throw new Error('@volcengine/openapi must export tlsOpenapi.TlsService');
+  }
+  const isAkSk = !options.apiKey;
+  const tlsService = new openapiModule.tlsOpenapi.TlsService({
+    host: options.tlsEndpoint || defaultTlsEndpointForRegion(options.region),
+    region: options.region,
+    accessKeyId: isAkSk ? options.ak : 'anonymous',
+    secretKey: isAkSk ? options.sk : 'anonymous',
+    protocol: 'https:',
+    version: '0.3.0',
+  });
+  const axiosConfig = options.apiKey
+    ? { proxy: false, headers: { 'x-tls-anonymous-identity': options.apiKey } }
+    : { proxy: false };
+
+  return {
+    isAkSk,
+    DescribeProjects: (payload: AnyRecord) => tlsService.DescribeProjects(payload, axiosConfig),
+    CreateProject: (payload: AnyRecord) => tlsService.CreateProject(payload, axiosConfig),
+    DescribeApps: (payload: AnyRecord) =>
+      tlsService.createAPI('DescribeApps', { method: 'GET' })(payload, axiosConfig),
+    CreateApp: (payload: AnyRecord) =>
+      tlsService.createAPI('CreateApp', { method: 'POST' })(payload, axiosConfig),
+    DescribeLogApps: (payload: AnyRecord) =>
+      tlsService.createAPI('DescribeLogApps', { method: 'GET' })(payload, axiosConfig),
+    DescribeTemplates: (payload: AnyRecord) =>
+      tlsService.createAPI('DescribeTemplates', { method: 'GET' })(payload, axiosConfig),
+  };
+}
+
+async function ensureTemplateId(tlsService: TlsServiceClient, options: InstallOptions): Promise<string> {
+  if (options.templateId) return options.templateId;
+  const response = await tlsService.DescribeTemplates({
+    TemplateName: options.templateName,
+    PageNumber: 1,
+    PageSize: 20,
+  });
+  const template = response.Templates?.find((item: AnyRecord) => item.TemplateName === options.templateName);
+  const templateId = String(template?.TemplateId || '').trim();
+  if (!templateId) {
+    throw new Error(
+      `DescribeTemplates did not return TemplateId for ${options.templateName}. Pass --template-id or --trace-topic-id.`,
+    );
+  }
+  return templateId;
+}
+
+async function ensureProjectId(tlsService: TlsServiceClient, options: InstallOptions): Promise<string> {
+  if (options.projectId) return options.projectId;
+  const response = await tlsService.DescribeProjects({
+    ProjectName: options.projectName,
+    PageSize: 100,
+    PageNumber: 1,
+  });
+  const project = response.Projects?.find((item: AnyRecord) => item.ProjectName === options.projectName);
+  const existingProjectId = String(project?.ProjectId || '').trim();
+  if (existingProjectId) return existingProjectId;
+  const created = await tlsService.CreateProject({
+    ProjectName: options.projectName,
+    Description: 'Pi observability',
+    Region: options.region,
+  });
+  const projectId = String(created.ProjectId || '').trim();
+  if (!projectId) throw new Error('CreateProject succeeded but did not return ProjectId');
+  return projectId;
+}
+
+async function ensureLogApp(
+  tlsService: TlsServiceClient,
+  options: InstallOptions,
+  projectId: string,
+): Promise<string> {
+  if (options.logAppId) return options.logAppId;
+  const appResponse = await tlsService.DescribeApps({
+    AppName: options.logAppName,
+    AppType: 'LogApp',
+  });
+  const total = appResponse.total ?? appResponse.Total ?? 0;
+  if (total > 0) {
+    const app = appResponse.apps?.[0] || appResponse.Apps?.[0];
+    const logAppId = String(app?.Resources?.[0]?.Id || app?.Sources?.[0]?.Id || '').trim();
+    if (logAppId) return logAppId;
+  }
+  const templateId = await ensureTemplateId(tlsService, options);
+  const created = await tlsService.CreateApp({
+    AppName: options.logAppName,
+    AppType: 'LogApp',
+    LogAppReq: {
+      LogAppName: options.logAppName,
+      LogAppType: options.logAppType,
+      ProjectId: projectId,
+    },
+    TemplateId: templateId,
+  });
+  const logAppId = String(created.Sources?.[0]?.Id || '').trim();
+  if (!logAppId) throw new Error('CreateApp succeeded but did not return Sources[0].Id');
+  return logAppId;
+}
+
+function topicMapFromLogApps(response: AnyRecord): Record<string, string> {
+  const topics = response?.LogApps?.[0]?.RelatedResourceList || [];
+  const topicMap: Record<string, string> = {};
+  for (const topic of topics) {
+    const resourceName = String(topic?.ResourceName || '');
+    const topicName = resourceName.split('_').filter(Boolean).at(-1);
+    const resourceId = String(topic?.ResourceID || '').trim();
+    if (topicName && resourceId) topicMap[topicName] = resourceId;
+  }
+  return topicMap;
+}
+
+async function ensureTlsResources(
+  options: InstallOptions,
+): Promise<{ created: boolean; logAppId?: string; traceTopicId?: string }> {
+  applyDerivedDefaults(options);
+  if (
+    options.skipTlsConfig ||
+    options.dryRun ||
+    options.apiKey ||
+    options.traceTopicId ||
+    !options.ak ||
+    !options.sk
+  ) {
+    return { created: false };
+  }
+  const openapiModule = await loadOpenapiModule();
+  const tlsService = createTlsService(options, openapiModule);
+  const projectId = await ensureProjectId(tlsService, options);
+
+  const logAppId = await ensureLogApp(tlsService, options, projectId);
+  options.logAppId = logAppId;
+  const logApps = await tlsService.DescribeLogApps({
+    PageNumber: 1,
+    PageSize: 20,
+    LogAppId: logAppId,
+    LogAppType: options.logAppType,
+  });
+
+  const topics = topicMapFromLogApps(logApps);
+  if (!options.traceTopicId) options.traceTopicId = topics.trace;
+  return { created: true, logAppId, traceTopicId: options.traceTopicId };
+}
+
+async function pathExists(filePath: string): Promise<boolean> {
+  try {
+    await fs.stat(filePath);
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
+async function assertPluginRuntime(pluginSource: string): Promise<void> {
+  const entry = path.join(pluginSource, 'dist', 'index.js');
+  const manifest = path.join(pluginSource, 'package.json');
+  if ((await pathExists(manifest)) && (await pathExists(entry))) return;
+  throw new Error(
+    `Plugin package is missing runtime files: ${pluginSource}. Expected dist/index.js and package.json.`,
+  );
+}
+
+function pluginPackageSpec(options: InstallOptions): string {
+  const version = options.pluginVersion || (options.beta ? 'beta' : 'latest');
+  return `${options.pluginPackage}@${version}`;
+}
+
+function readLocalPluginSourceEnv(): { key: string; value: string } | undefined {
+  for (const key of LOCAL_PLUGIN_SOURCE_ENV_KEYS) {
+    const value = readEnvString(key);
+    if (value) return { key, value };
+  }
+  return undefined;
+}
+
+async function findLocalPluginSource(): Promise<string | undefined> {
+  const explicit = readLocalPluginSourceEnv();
+  if (!explicit) return undefined;
+  const manifest = await readJsonFile<{ publishConfig?: { directory?: string } }>(
+    path.join(explicit.value, 'package.json'),
+    {},
+  );
+  const publishDirectory = manifest.publishConfig?.directory;
+  const candidates = publishDirectory ? [path.join(explicit.value, publishDirectory)] : [explicit.value];
+  for (const candidate of candidates) {
+    try {
+      await assertPluginRuntime(candidate);
+      return candidate;
+    } catch {
+      // Continue so the final error includes the env var value.
+    }
+  }
+  throw new Error(
+    `${explicit.key} does not point to a built Pi runtime package: ${explicit.value}. Run the plugin build first.`,
+  );
+}
+
+async function readPluginVersion(pluginSource: string): Promise<string | undefined> {
+  const manifest = await readJsonFile<{ version?: string }>(path.join(pluginSource, 'package.json'), {});
+  return manifest.version;
+}
+
+function piCliEnv(options: InstallOptions): NodeJS.ProcessEnv {
+  return {
+    ...process.env,
+    npm_config_registry: options.registry,
+    NPM_CONFIG_REGISTRY: options.registry,
+  };
+}
+
+function commandErrorDetail(error: unknown): string {
+  if (error && typeof error === 'object' && 'stderr' in error) {
+    const stderr = String((error as { stderr?: unknown }).stderr || '').trim();
+    if (stderr) return stderr;
+  }
+  return error instanceof Error ? error.message : String(error);
+}
+
+async function execPiCli(options: InstallOptions, args: string[]): Promise<void> {
+  try {
+    await execFileAsync(options.piBin, args, { env: piCliEnv(options) });
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      throw new Error(
+        `Pi CLI executable not found: ${options.piBin}. Install Pi CLI, make it available on PATH, or pass --pi-bin <path> / set PI_TLS_PI_BIN. The installer needs to run "${options.piBin} ${args.join(' ')}".`,
+      );
+    }
+    throw new Error(
+      `Pi CLI command failed: ${options.piBin} ${args.join(' ')}\n${commandErrorDetail(error)}`,
+    );
+  }
+}
+
+async function installPlugin(options: InstallOptions): Promise<PluginInstallResult> {
+  const localSource = await findLocalPluginSource();
+  const packageSpec = pluginPackageSpec(options);
+  const source = localSource || `npm:${packageSpec}`;
+  if (options.dryRun) {
+    return {
+      source,
+      target: source,
+      packageSpec: localSource ? undefined : packageSpec,
+      version: localSource ? await readPluginVersion(localSource) : undefined,
+      dryRun: true,
+    };
+  }
+  if (localSource) {
+    await execPiCli(options, ['install', localSource]);
+    return {
+      source: localSource,
+      target: localSource,
+      version: await readPluginVersion(localSource),
+    };
+  }
+  await execPiCli(options, ['install', source]);
+  return { source, target: source, packageSpec };
+}
+
+async function readJsonFile<T>(filePath: string, fallback: T): Promise<T> {
+  try {
+    return JSON.parse(await fs.readFile(filePath, 'utf8')) as T;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return fallback;
+    throw error;
+  }
+}
+
+async function writeJsonFile(filePath: string, value: unknown, mode?: number): Promise<void> {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  if (mode) {
+    await fs.writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, { mode });
+  } else {
+    await fs.writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+  }
+}
+
+function envLine(key: string, value?: string | null): string | undefined {
+  if (value === undefined || value === null || value === '') return undefined;
+  return `${key}=${String(value)}`;
+}
+
+function buildTlsEnv(options: InstallOptions): string {
+  const lines = [
+    '# Generated by tls-observer-pi installer.',
+    '# Keep this file local because it can contain credentials.',
+    envLine('PI_TLS_REGION', options.region),
+    envLine('PI_TLS_ENDPOINT', options.tlsEndpoint),
+    envLine('PI_TLS_TRACE_TOPIC_ID', options.traceTopicId),
+    envLine('PI_TLS_API_KEY', options.apiKey),
+    envLine('PI_TLS_AK', options.ak),
+    envLine('PI_TLS_SK', options.sk),
+    envLine('PI_TLS_AUTH_MODE', options.authMode),
+    envLine('PI_TLS_EXPORT_TIMEOUT_MS', options.exportTimeoutMs),
+    envLine('PI_TLS_CAPTURE_CONTENT', options.captureContent),
+    envLine('PI_TLS_DATA_ROOT', options.dataRoot),
+  ].filter(Boolean);
+  return `${lines.join('\n')}\n`;
+}
+
+async function writeTlsEnv(options: InstallOptions): Promise<string | null> {
+  if (options.skipTlsConfig) return null;
+  const envTargetExists = await pathExists(options.envTarget);
+  if (envTargetExists && !options.force) {
+    throw new Error(`TLS env target exists: ${options.envTarget}. Re-run with --force.`);
+  }
+  await writeJsonFile(path.join(options.dataRoot, 'state', 'install.json'), {
+    installed_at: new Date().toISOString(),
+    plugin_id: PLUGIN_PACKAGE_NAME,
+    log_app_id: options.logAppId,
+    env_target: options.envTarget,
+  });
+  await fs.mkdir(path.dirname(options.envTarget), { recursive: true, mode: 0o700 });
+  if (envTargetExists) {
+    await fs.chmod(options.envTarget, 0o600).catch(() => undefined);
+    await fs.rm(options.envTarget, { force: true });
+  }
+  await fs.writeFile(options.envTarget, buildTlsEnv(options), { flag: 'wx', mode: 0o600 });
+  await fs.chmod(options.envTarget, 0o600);
+  return options.envTarget;
+}
+
+function printCompletion({
+  plugin,
+  envTarget,
+}: {
+  plugin: PluginInstallResult;
+  envTarget: string | null;
+}): void {
+  console.log('');
+  console.log(plugin.dryRun ? 'Dry run complete' : 'Install complete');
+  console.log(`  Plugin: ${plugin.target}`);
+  if (plugin.packageSpec) console.log(`  Plugin package: ${plugin.packageSpec}`);
+  if (plugin.version) console.log(`  Plugin version: ${plugin.version}`);
+  console.log(`  TLS env: ${envTarget || 'skipped'}`);
+  console.log('');
+  console.log('数据访问说明');
+  console.log('安装后，插件会读取 Pi 运行过程中的会话和生命周期事件');
+  console.log('用户请求、模型回复、工具调用记录和 token 用量会整理成诊断数据，上传到你配置的火山引擎 TLS');
+  console.log('如配置 API Key 或 AK/SK，凭据只写入本机 env 文件，用于上传鉴权');
+  console.log('');
+  console.log('Next steps:');
+  console.log('  1. Restart Pi environment.');
+  console.log('  2. Run one Pi turn.');
+  console.log('  3. Check TLS Trace Topic for agent.turn.');
+}
+
+async function run(argv: string[] = process.argv.slice(2)): Promise<void> {
+  const parsed = parseCliOptions(argv);
+  if (parsed.help) {
+    printHelp();
+    return;
+  }
+  const options = await collectInteractiveOptions(parsed);
+  if (!options.skipTlsConfig) {
+    const resourceResult = await ensureTlsResources(options);
+    if (resourceResult.created && !options.traceTopicId) {
+      throw new Error('TLS LogApp was created but trace topic discovery failed. Pass --trace-topic-id.');
+    }
+    applyDerivedDefaults(options);
+    validateTlsConfig(options);
+  }
+  const plugin = await installPlugin(options);
+  const envTarget = await writeTlsEnv(options);
+  printCompletion({ plugin, envTarget });
+}
+
+async function writeEnvFile(options: InstallOptions): Promise<void> {
+  await writeTlsEnv(options);
+}
+
+const runInstaller = run;
+const installPiPackage = installPlugin;
+
+export {
+  applyDerivedDefaults,
+  buildTlsEnv,
+  findLocalPluginSource,
+  installPiPackage,
+  installPlugin,
+  parseCliOptions,
+  pluginPackageSpec,
+  run,
+  runInstaller,
+  validateBaseTlsConfig,
+  validateTlsConfig,
+  writeEnvFile,
+  writeTlsEnv,
+};