@volcengine/tls-observer-trae-install 0.0.2

package/src/installer/installer-runner.ts

@@ -0,0 +1,884 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { execFile, execFileSync, spawn } from 'node:child_process';
+import { homedir, tmpdir } 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;
+  skipTlsConfig: boolean;
+  healthCheck: boolean;
+  registry: string;
+  pluginPackage: string;
+  pluginVersion?: string;
+  pluginTarget: string;
+  envTarget: string;
+  dataRoot: string;
+  hookConfigTarget: string;
+  region?: string;
+  tlsEndpoint?: string;
+  otelEndpoint?: string;
+  traceTopicId?: string;
+  apiKey?: string;
+  ak?: string;
+  sk?: string;
+  authMode: string;
+  exportTimeoutMs: string;
+  exportTimeoutRetries: string;
+  captureContent: 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;
+};
+
+const execFileAsync = promisify(execFile);
+const PLUGIN_NAME = 'tls-observer-trae';
+const PLUGIN_PACKAGE_NAME = '@volcengine/tls-observer-trae';
+const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
+const DEFAULT_TRAE_ROOT = path.join(homedir(), '.trae-cn');
+const DEFAULT_PLUGIN_TARGET = path.join(DEFAULT_TRAE_ROOT, 'plugins', PLUGIN_NAME);
+const DEFAULT_ENV_TARGET = path.join(DEFAULT_TRAE_ROOT, 'tls-observer-trae.env');
+const DEFAULT_DATA_ROOT = path.join(DEFAULT_TRAE_ROOT, 'plugins', 'data', PLUGIN_NAME);
+const DEFAULT_HOOK_CONFIG_TARGET = path.join(DEFAULT_TRAE_ROOT, 'hooks.json');
+const DEFAULT_REGION = 'cn-beijing';
+const DEFAULT_TLS_ENDPOINT = 'tls-cn-beijing.volces.com';
+const DEFAULT_PROJECT_NAME = 'trae_observability';
+const DEFAULT_APP_NAME_PREFIX = 'trae-observability';
+const DEFAULT_LOG_APP_TYPE = 'Trae';
+const DEFAULT_TEMPLATE_NAME = 'Trae';
+
+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.otelEndpoint) {
+    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: InstallOptions = {
+    help: false,
+    nonInteractive: readEnvBool('TRAE_TLS_INSTALL_NON_INTERACTIVE'),
+    force: readEnvBool('TRAE_TLS_INSTALL_FORCE'),
+    beta: readEnvBool('TRAE_TLS_INSTALL_BETA'),
+    skipTlsConfig: readEnvBool('TRAE_TLS_INSTALL_SKIP_TLS_CONFIG'),
+    healthCheck: readEnvBool('TRAE_TLS_INSTALL_HEALTH_CHECK'),
+    registry:
+      readEnvString('TRAE_TLS_NPM_REGISTRY') ||
+      readEnvString('npm_config_registry') ||
+      readEnvString('NPM_CONFIG_REGISTRY') ||
+      DEFAULT_REGISTRY,
+    pluginPackage: readEnvString('TRAE_TLS_PLUGIN_PACKAGE') || PLUGIN_PACKAGE_NAME,
+    pluginVersion: readEnvString('TRAE_TLS_PLUGIN_VERSION'),
+    pluginTarget: readEnvString('TRAE_PLUGIN_TARGET') || DEFAULT_PLUGIN_TARGET,
+    envTarget: readEnvString('TRAE_TLS_ENV_TARGET') || DEFAULT_ENV_TARGET,
+    dataRoot: readEnvString('TRAE_TLS_DATA_ROOT') || DEFAULT_DATA_ROOT,
+    hookConfigTarget: readEnvString('TRAE_HOOK_CONFIG_TARGET') || DEFAULT_HOOK_CONFIG_TARGET,
+    region: readEnvString('TRAE_TLS_REGION') || DEFAULT_REGION,
+    tlsEndpoint: readEnvString('TRAE_TLS_ENDPOINT'),
+    otelEndpoint: readEnvString('TRAE_TLS_OTEL_ENDPOINT'),
+    traceTopicId: readEnvString('TRAE_TLS_TRACE_TOPIC_ID'),
+    apiKey: readEnvString('TRAE_TLS_API_KEY'),
+    ak: readEnvString('TRAE_TLS_AK'),
+    sk: readEnvString('TRAE_TLS_SK'),
+    authMode: readEnvString('TRAE_TLS_AUTH_MODE') || 'header',
+    exportTimeoutMs: readEnvString('TRAE_TLS_EXPORT_TIMEOUT_MS') || '20000',
+    exportTimeoutRetries: readEnvString('TRAE_TLS_EXPORT_TIMEOUT_RETRIES') || '1',
+    captureContent: readEnvString('TRAE_TLS_CAPTURE_CONTENT') || '1',
+    projectId: readEnvString('TRAE_TLS_PROJECT_ID'),
+    projectName: readEnvString('TRAE_TLS_PROJECT_NAME'),
+    logAppId: readEnvString('TRAE_TLS_LOG_APP_ID'),
+    logAppName: readEnvString('TRAE_TLS_LOG_APP_NAME'),
+    logAppType: readEnvString('TRAE_TLS_LOG_APP_TYPE') || DEFAULT_LOG_APP_TYPE,
+    templateName: readEnvString('TRAE_TLS_TEMPLATE_NAME') || DEFAULT_TEMPLATE_NAME,
+    templateId: readEnvString('TRAE_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 === '--skip-tls-config') options.skipTlsConfig = true;
+    else if (current === '--health-check') options.healthCheck = true;
+    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 === '--plugin-target') options.pluginTarget = 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 === '--hook-config-target') options.hookConfigTarget = takeArg(argv, index++, current);
+    else if (current === '--region') options.region = takeArg(argv, index++, current);
+    else if (current === '--tls-endpoint') options.tlsEndpoint = takeArg(argv, index++, current);
+    else if (current === '--otel-endpoint') options.otelEndpoint = 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 === '--export-timeout-retries')
+      options.exportTimeoutRetries = takeArg(argv, index++, current);
+    else if (current === '--capture-content') options.captureContent = 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 Trae installer
+
+Usage:
+  tls-observer-trae-install [options]
+  npm exec -y --package=@volcengine/tls-observer-trae-install -- tls-observer-trae-install [options]
+
+Options:
+  --non-interactive              Read required inputs from flags/env
+  --force                        Overwrite existing runtime/env files
+  --beta                         Install @volcengine/tls-observer-trae@beta instead of @latest
+  --skip-tls-config              Install runtime without writing TLS env
+  --health-check                 Check ctx-cli/CFS environment after install
+  --registry <url>               NPM registry. Default: https://registry.npmjs.org
+  --plugin-version <version>     Exact runtime version or dist-tag. Overrides --beta
+  --plugin-target <path>         Default: ~/.trae-cn/plugins/tls-observer-trae
+  --env-target <path>            Default: ~/.trae-cn/tls-observer-trae.env
+  --data-root <path>             Default: ~/.trae-cn/plugins/data/tls-observer-trae
+  --hook-config-target <path>    Default: ~/.trae-cn/hooks.json
+  --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
+  --capture-content <0|1>        Default: 1
+`);
+}
+
+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: already set, press enter to keep\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 TRAE_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 && !options.otelEndpoint) missing.push('--tls-endpoint or --region');
+  if (!options.traceTopicId) missing.push('--trace-topic-id or TRAE_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 Trae 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('TRAE_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: 'Trae 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.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 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 assertPluginRuntime(pluginSource: string): Promise<void> {
+  const entry = path.join(pluginSource, 'dist', 'index.js');
+  const hooks = path.join(pluginSource, 'hooks', 'hooks.json');
+  if ((await pathExists(entry)) && (await pathExists(hooks))) return;
+  throw new Error(
+    `Runtime package is missing files: ${pluginSource}. Expected dist/index.js and hooks/hooks.json.`,
+  );
+}
+
+function pluginPackagePath(tempRoot: string, packageName: string): string {
+  return path.join(tempRoot, 'node_modules', ...packageName.split('/'));
+}
+
+function pluginPackageSpec(options: InstallOptions): string {
+  const version = options.pluginVersion || (options.beta ? 'beta' : 'latest');
+  return `${options.pluginPackage}@${version}`;
+}
+
+async function installPluginPackageToTemp(options: InstallOptions): Promise<{
+  root: string;
+  source: string;
+  packageSpec: string;
+}> {
+  const root = await fs.mkdtemp(path.join(tmpdir(), 'tls-observer-trae-plugin-'));
+  const packageSpec = pluginPackageSpec(options);
+  const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  const args = [
+    'install',
+    '--prefix',
+    root,
+    '--ignore-scripts',
+    '--no-audit',
+    '--no-fund',
+    '--omit=dev',
+    '--registry',
+    options.registry,
+    packageSpec,
+  ];
+  await execFileAsync(npm, args, { timeout: 120_000 });
+  const source = pluginPackagePath(root, options.pluginPackage);
+  await assertPluginRuntime(source);
+  return { root, source, packageSpec };
+}
+
+async function findLocalPluginSource(): Promise<string | undefined> {
+  const explicit = readEnvString('TRAE_TLS_PLUGIN_SOURCE');
+  if (!explicit) return undefined;
+  const manifest = await readJsonFile<{ publishConfig?: { directory?: string } }>(
+    path.join(explicit, 'package.json'),
+    {},
+  );
+  const publishDirectory = manifest.publishConfig?.directory;
+  const candidates = publishDirectory ? [path.join(explicit, publishDirectory)] : [explicit];
+  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(`TRAE_TLS_PLUGIN_SOURCE does not point to a built runtime package: ${explicit}.`);
+}
+
+async function readPluginVersion(pluginSource: string): Promise<string | undefined> {
+  const manifest = await readJsonFile<{ version?: string }>(path.join(pluginSource, 'package.json'), {});
+  return manifest.version;
+}
+
+async function installPlugin(options: InstallOptions): Promise<PluginInstallResult> {
+  if ((await pathExists(options.pluginTarget)) && !options.force) {
+    throw new Error(`Plugin target exists: ${options.pluginTarget}. Re-run with --force.`);
+  }
+
+  const localSource = await findLocalPluginSource();
+  const tempInstall = localSource ? undefined : await installPluginPackageToTemp(options);
+  const source = localSource || tempInstall!.source;
+
+  await fs.rm(options.pluginTarget, { recursive: true, force: true });
+  await fs.mkdir(options.pluginTarget, { recursive: true });
+  for (const entry of ['dist', 'hooks', 'README.md', 'package.json'] as const) {
+    await fs.cp(path.join(source, entry), path.join(options.pluginTarget, entry), { recursive: true });
+  }
+
+  const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  await new Promise<void>((resolve, reject) => {
+    const child = spawn(npm, ['install', '--omit=dev', '--ignore-scripts', '--no-audit', '--no-fund'], {
+      cwd: options.pluginTarget,
+      stdio: 'inherit',
+    });
+    const timer = setTimeout(() => {
+      child.kill();
+      reject(new Error('npm install timed out after 120s'));
+    }, 120_000);
+    child.on('exit', (code) => {
+      clearTimeout(timer);
+      if (code === 0) resolve();
+      else reject(new Error(`npm install exited with code ${code}`));
+    });
+    child.on('error', reject);
+  });
+
+  if (tempInstall) await fs.rm(tempInstall.root, { recursive: true, force: true });
+  return {
+    source,
+    target: options.pluginTarget,
+    packageSpec: tempInstall?.packageSpec,
+    version: await readPluginVersion(source),
+  };
+}
+
+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-trae installer.',
+    '# Keep this file local because it can contain credentials.',
+    envLine('TRAE_TLS_REGION', options.region),
+    envLine('TRAE_TLS_ENDPOINT', options.tlsEndpoint),
+    envLine('TRAE_TLS_OTEL_ENDPOINT', options.otelEndpoint),
+    envLine('TRAE_TLS_TRACE_TOPIC_ID', options.traceTopicId),
+    envLine('TRAE_TLS_API_KEY', options.apiKey),
+    envLine('TRAE_TLS_AK', options.ak),
+    envLine('TRAE_TLS_SK', options.sk),
+    envLine('TRAE_TLS_AUTH_MODE', options.authMode),
+    envLine('TRAE_TLS_EXPORT_TIMEOUT_MS', options.exportTimeoutMs),
+    envLine('TRAE_TLS_EXPORT_TIMEOUT_RETRIES', options.exportTimeoutRetries),
+    envLine('TRAE_TLS_CAPTURE_CONTENT', options.captureContent),
+    envLine('TRAE_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;
+  if ((await pathExists(options.envTarget)) && !options.force) {
+    throw new Error(`TLS env target exists: ${options.envTarget}. Re-run with --force.`);
+  }
+  await fs.mkdir(path.dirname(options.envTarget), { recursive: true });
+  await fs.writeFile(options.envTarget, buildTlsEnv(options), { mode: 0o600 });
+  return options.envTarget;
+}
+
+async function writeHookReferenceConfig(options: InstallOptions): Promise<string> {
+  const shellQuote = (value: string): string => `'${value.replace(/'/g, "'\\''")}'`;
+  const command = `TRAE_TLS_ENV_FILE=${shellQuote(options.envTarget)} node ${shellQuote(
+    path.join(options.pluginTarget, 'dist', 'index.js'),
+  )}`;
+  const config = {
+    version: 1,
+    hooks: {
+      UserPromptSubmit: [
+        {
+          hooks: [
+            {
+              type: 'command',
+              command,
+              timeout: 30,
+            },
+          ],
+        },
+      ],
+      PreToolUse: [
+        {
+          hooks: [
+            {
+              type: 'command',
+              command,
+              timeout: 30,
+            },
+          ],
+        },
+      ],
+      PostToolUse: [
+        {
+          hooks: [
+            {
+              type: 'command',
+              command,
+              timeout: 30,
+            },
+          ],
+        },
+      ],
+      Stop: [
+        {
+          hooks: [
+            {
+              type: 'command',
+              command,
+              timeout: 30,
+            },
+          ],
+        },
+      ],
+    },
+  };
+  await fs.mkdir(path.dirname(options.hookConfigTarget), { recursive: true });
+  await fs.writeFile(options.hookConfigTarget, `${JSON.stringify(config, null, 2)}\n`, 'utf8');
+  return options.hookConfigTarget;
+}
+
+async function writeInstallState(options: InstallOptions, plugin: PluginInstallResult): Promise<void> {
+  const target = path.join(options.dataRoot, 'state', 'install.json');
+  await fs.mkdir(path.dirname(target), { recursive: true });
+  await fs.writeFile(
+    target,
+    `${JSON.stringify(
+      {
+        installed_at: new Date().toISOString(),
+        plugin_name: PLUGIN_NAME,
+        plugin_target: plugin.target,
+        env_target: options.envTarget,
+        hook_config_target: options.hookConfigTarget,
+      },
+      null,
+      2,
+    )}\n`,
+    'utf8',
+  );
+}
+
+async function runHealthCheck(options: InstallOptions): Promise<Record<string, unknown>> {
+  const missingCfsEnv = ['CFS_TOKEN', 'CFS_IPC_NAME'].filter((key) => !process.env[key]?.trim());
+  const result: Record<string, unknown> = {
+    ctx_cli_on_path: false,
+    contextfs_ready: missingCfsEnv.length === 0,
+    contextfs_missing_env: missingCfsEnv,
+    cfs_token_present: Boolean(process.env.CFS_TOKEN),
+    cfs_ipc_name_present: Boolean(process.env.CFS_IPC_NAME),
+    cfs_transport: process.env.CFS_TRANSPORT || 'ipc',
+  };
+  try {
+    await execFileAsync('ctx-cli', ['--help'], {
+      timeout: 5_000,
+      env: {
+        ...process.env,
+        CFS_TRANSPORT: process.env.CFS_TRANSPORT || 'ipc',
+      },
+    });
+    result.ctx_cli_on_path = true;
+  } catch (error) {
+    result.ctx_cli_error = error instanceof Error ? error.message : String(error);
+  }
+  if (!result.contextfs_ready) {
+    result.note =
+      'ctx-cli can only read context:// resources inside Trae hook/toolhost environment with CFS_TOKEN and CFS_IPC_NAME.';
+  }
+  const target = path.join(options.dataRoot, 'state', 'health-check.json');
+  await fs.mkdir(path.dirname(target), { recursive: true });
+  await fs.writeFile(target, `${JSON.stringify(result, null, 2)}\n`, 'utf8');
+  return result;
+}
+
+function printCompletion({
+  plugin,
+  envTarget,
+  hookConfigTarget,
+  health,
+}: {
+  plugin: PluginInstallResult;
+  envTarget: string | null;
+  hookConfigTarget: string;
+  health?: Record<string, unknown>;
+}): void {
+  console.log('');
+  console.log('Install complete');
+  console.log(`  Runtime: ${plugin.target}`);
+  if (plugin.packageSpec) console.log(`  Runtime package: ${plugin.packageSpec}`);
+  if (plugin.version) console.log(`  Runtime version: ${plugin.version}`);
+  console.log(`  TLS env: ${envTarget || 'skipped'}`);
+  console.log(`  Hook reference: ${hookConfigTarget}`);
+  if (health) console.log(`  Health check: ${JSON.stringify(health)}`);
+  console.log('');
+  console.log('Next steps:');
+  console.log('  1. Confirm Trae hook/plugin config path for your Trae build.');
+  console.log('  2. Wire the command from the hook reference file.');
+  console.log('  3. Run one Trae turn and check logs/send/latest.send-log.json under the data root.');
+}
+
+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);
+  const hookConfigTarget = await writeHookReferenceConfig(options);
+  await writeInstallState(options, plugin);
+  const health = options.healthCheck ? await runHealthCheck(options) : undefined;
+  printCompletion({ plugin, envTarget, hookConfigTarget, health });
+}
+
+export { run };