@volcengine/tls-observer-cursor-install 0.0.4

package/src/installer/installer-runner.ts

@@ -0,0 +1,942 @@
+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;
+  advancedPaths: boolean;
+  registry: string;
+  pluginPackage: string;
+  pluginVersion?: string;
+  hooksPath: string;
+  pluginTarget: string;
+  envTarget: string;
+  dataRoot: string;
+  region?: string;
+  otelEndpoint?: string;
+  traceTopicId?: string;
+  apiKey?: string;
+  ak?: string;
+  sk?: string;
+  authMode: string;
+  exportTimeoutMs: string;
+  exportTimeoutRetries: 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;
+};
+
+const execFileAsync = promisify(execFile);
+const PLUGIN_NAME = 'tls-observer-cursor';
+const PLUGIN_PACKAGE_NAME = '@volcengine/tls-observer-cursor';
+const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
+const DEFAULT_HOOKS_PATH = path.join(homedir(), '.cursor', 'hooks.json');
+const DEFAULT_INSTALL_ROOT = path.join(homedir(), '.cursor', PLUGIN_NAME);
+const DEFAULT_ENV_TARGET = path.join(homedir(), '.cursor', 'tls-observer-cursor.env');
+const DEFAULT_PLUGIN_TARGET = path.join(DEFAULT_INSTALL_ROOT, 'plugin');
+const DEFAULT_DATA_ROOT = path.join(homedir(), '.cursor', 'plugins', 'data', 'tls-observer-cursor');
+const DEFAULT_REGION = 'cn-beijing';
+const DEFAULT_PROJECT_NAME = 'cursor_observability';
+const DEFAULT_APP_NAME_PREFIX = 'cursor-observability';
+const DEFAULT_TLS_ENDPOINT = 'tls-cn-beijing.volces.com';
+const DEFAULT_LOG_APP_TYPE = 'Cursor';
+const DEFAULT_TEMPLATE_NAME = 'Cursor';
+const CURSOR_HOOK_EVENTS = [
+  ['beforeSubmitPrompt', 30],
+  ['stop', 120],
+  ['sessionEnd', 30],
+] as const;
+
+type CursorHooksFile = AnyRecord & {
+  version?: number;
+  hooks?: Record<string, unknown>;
+};
+
+type HookEventConfig = {
+  eventName: string;
+  timeout: number;
+};
+
+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) {
+    if (!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 = {
+    help: false,
+    nonInteractive: readEnvBool('CURSOR_TLS_INSTALL_NON_INTERACTIVE'),
+    force: readEnvBool('CURSOR_TLS_INSTALL_FORCE'),
+    beta: readEnvBool('CURSOR_TLS_INSTALL_BETA'),
+    skipTlsConfig: readEnvBool('CURSOR_TLS_INSTALL_SKIP_TLS_CONFIG'),
+    advancedPaths: readEnvBool('CURSOR_TLS_INSTALL_ADVANCED_PATHS'),
+    registry:
+      readEnvString('CURSOR_TLS_NPM_REGISTRY') ||
+      readEnvString('npm_config_registry') ||
+      readEnvString('NPM_CONFIG_REGISTRY') ||
+      DEFAULT_REGISTRY,
+    pluginPackage: readEnvString('CURSOR_TLS_PLUGIN_PACKAGE') || PLUGIN_PACKAGE_NAME,
+    pluginVersion: readEnvString('CURSOR_TLS_PLUGIN_VERSION'),
+    hooksPath: readEnvString('CURSOR_HOOKS_PATH') || DEFAULT_HOOKS_PATH,
+    pluginTarget:
+      readEnvString('CURSOR_TLS_PLUGIN_TARGET') ||
+      readEnvString('CURSOR_PLUGIN_TARGET') ||
+      DEFAULT_PLUGIN_TARGET,
+    envTarget: readEnvString('CURSOR_TLS_ENV_TARGET') || DEFAULT_ENV_TARGET,
+    dataRoot: readEnvString('CURSOR_TLS_DATA_ROOT') || DEFAULT_DATA_ROOT,
+    region: readEnvString('CURSOR_TLS_REGION') || DEFAULT_REGION,
+    otelEndpoint: readEnvString('CURSOR_TLS_OTEL_ENDPOINT'),
+    traceTopicId: readEnvString('CURSOR_TLS_TRACE_TOPIC_ID'),
+    apiKey: readEnvString('CURSOR_TLS_API_KEY'),
+    ak: readEnvString('CURSOR_TLS_AK'),
+    sk: readEnvString('CURSOR_TLS_SK'),
+    authMode: readEnvString('CURSOR_TLS_AUTH_MODE') || 'header',
+    exportTimeoutMs: readEnvString('CURSOR_TLS_EXPORT_TIMEOUT_MS') || '20000',
+    exportTimeoutRetries: readEnvString('CURSOR_TLS_EXPORT_TIMEOUT_RETRIES') || '1',
+    captureContent: readEnvString('CURSOR_TLS_CAPTURE_CONTENT') || '1',
+    tlsEndpoint: readEnvString('CURSOR_TLS_ENDPOINT'),
+    projectId: readEnvString('CURSOR_TLS_PROJECT_ID'),
+    projectName: readEnvString('CURSOR_TLS_PROJECT_NAME'),
+    logAppId: readEnvString('CURSOR_TLS_LOG_APP_ID'),
+    logAppName: readEnvString('CURSOR_TLS_LOG_APP_NAME'),
+    logAppType: readEnvString('CURSOR_TLS_LOG_APP_TYPE') || DEFAULT_LOG_APP_TYPE,
+    templateName: readEnvString('CURSOR_TLS_TEMPLATE_NAME') || DEFAULT_TEMPLATE_NAME,
+    templateId: readEnvString('CURSOR_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 === '--advanced-paths') options.advancedPaths = 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 === '--hooks-path') options.hooksPath = 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 === '--region') options.region = 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 === '--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 Cursor installer
+
+Usage:
+  tls-observer-cursor-install [options]
+  npm exec -y --package=@volcengine/tls-observer-cursor-install -- tls-observer-cursor-install [options]
+
+Options:
+  --non-interactive              Read required inputs from flags/env
+  --force                        Overwrite existing plugin/env files
+  --beta                         Install @volcengine/tls-observer-cursor@beta instead of @latest
+  --skip-tls-config              Install plugin without writing TLS env
+  --advanced-paths               Prompt for Cursor path overrides
+  --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
+  --otel-endpoint <url>          Deprecated legacy endpoint alias
+  --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
+  --hooks-path <path>            Default: ~/.cursor/hooks.json
+  --plugin-target <path>         Default: ~/.cursor/tls-observer-cursor/plugin
+  --env-target <path>            Default: ~/.cursor/tls-observer-cursor.env
+  --data-root <path>             Default: ~/.cursor/plugins/data/tls-observer-cursor
+`);
+}
+
+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 CURSOR_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, --region, or legacy --otel-endpoint');
+  }
+  if (!options.traceTopicId) missing.push('--trace-topic-id or CURSOR_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 Cursor installer');
+    if (options.advancedPaths) {
+      options.hooksPath = await promptRequired(rl, 'Cursor hooks path', options.hooksPath);
+      options.pluginTarget = await promptRequired(rl, 'Cursor plugin target', options.pluginTarget);
+      options.envTarget = await promptRequired(rl, 'TLS env output path', options.envTarget);
+      options.dataRoot = await promptRequired(rl, 'Plugin data root', options.dataRoot);
+    }
+    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('CURSOR_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: 'Cursor 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 assertPluginRuntime(pluginSource: string): Promise<void> {
+  const hooks = path.join(pluginSource, 'hooks', 'hooks.json');
+  const entry = path.join(pluginSource, 'dist', 'index.js');
+  const manifest = path.join(pluginSource, 'package.json');
+  if ((await pathExists(manifest)) && (await pathExists(hooks)) && (await pathExists(entry))) return;
+  throw new Error(
+    `Plugin package is missing runtime files: ${pluginSource}. Expected dist/index.js, hooks/hooks.json, and package.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-cursor-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,
+  ];
+
+  try {
+    await execFileAsync(npm, args, { timeout: 120_000 });
+  } catch (error) {
+    const detail =
+      error && typeof error === 'object' && 'stderr' in error
+        ? String((error as { stderr?: unknown }).stderr || '')
+        : error instanceof Error
+          ? error.message
+          : String(error);
+    throw new Error(`Failed to install plugin package ${packageSpec} from ${options.registry}: ${detail}`);
+  }
+
+  const source = pluginPackagePath(root, options.pluginPackage);
+  await assertPluginRuntime(source);
+  return { root, source, packageSpec };
+}
+
+async function writeHookWrapper(options: InstallOptions): Promise<void> {
+  const source = [
+    '#!/usr/bin/env node',
+    `process.env.CURSOR_TLS_ENV_FILE ??= ${JSON.stringify(options.envTarget)};`,
+    "await import('./dist/index.js');",
+    '',
+  ].join('\n');
+  await fs.writeFile(path.join(options.pluginTarget, 'run-hook.mjs'), source, { mode: 0o755 });
+}
+
+async function findLocalPluginSource(): Promise<string | undefined> {
+  const explicit = readEnvString('CURSOR_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(
+    `CURSOR_PLUGIN_SOURCE does not point to a built runtime package: ${explicit}. 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;
+}
+
+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(path.dirname(options.pluginTarget), { recursive: true });
+  await fs.mkdir(options.pluginTarget, { recursive: true });
+  const runtimeEntries = ['dist', 'hooks', 'README.md', 'package.json'] as const;
+  try {
+    for (const entry of runtimeEntries) {
+      await fs.cp(path.join(source, entry), path.join(options.pluginTarget, entry), { recursive: true });
+    }
+    await writeHookWrapper(options);
+    const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+    console.log('插件依赖安装中，请稍后...');
+    try {
+      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);
+      });
+    } catch (error) {
+      const detail =
+        error && typeof error === 'object' && 'stderr' in error
+          ? String((error as { stderr?: unknown }).stderr || '')
+          : error instanceof Error
+            ? error.message
+            : String(error);
+      throw new Error(`Failed to install plugin dependencies at ${options.pluginTarget}: ${detail}`);
+    }
+    return {
+      source,
+      target: options.pluginTarget,
+      packageSpec: tempInstall?.packageSpec,
+      version: await readPluginVersion(source),
+    };
+  } finally {
+    if (tempInstall) await fs.rm(tempInstall.root, { recursive: true, force: true });
+  }
+}
+
+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 commandQuote(value: string): string {
+  if (process.platform === 'win32') return `"${value.replace(/"/g, '\\"')}"`;
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}
+
+function hookCommand(options: InstallOptions): string {
+  const nodeBin = commandQuote(process.execPath);
+  const wrapper = commandQuote(path.join(options.pluginTarget, 'run-hook.mjs'));
+  return `${nodeBin} ${wrapper}`;
+}
+
+function isManagedHookEntry(entry: unknown): boolean {
+  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) return false;
+  const command = String((entry as AnyRecord).command || '');
+  return (
+    command.includes(PLUGIN_NAME) ||
+    command.includes(PLUGIN_PACKAGE_NAME) ||
+    command.includes('CURSOR_TLS_OBSERVER_ROOT')
+  );
+}
+
+function fallbackHookEvents(): HookEventConfig[] {
+  return CURSOR_HOOK_EVENTS.map(([eventName, timeout]) => ({ eventName, timeout }));
+}
+
+function parseHookEventsManifest(value: unknown): HookEventConfig[] {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return [];
+  const hooks = (value as AnyRecord).hooks;
+  if (!hooks || typeof hooks !== 'object' || Array.isArray(hooks)) return [];
+
+  const events: HookEventConfig[] = [];
+  for (const [eventName, entries] of Object.entries(hooks)) {
+    if (!Array.isArray(entries) || entries.length === 0) continue;
+    const firstEntry = entries.find((entry) => entry && typeof entry === 'object' && !Array.isArray(entry));
+    const timeout = Number((firstEntry as AnyRecord | undefined)?.timeout);
+    events.push({
+      eventName,
+      timeout: Number.isFinite(timeout) && timeout > 0 ? timeout : 30,
+    });
+  }
+  return events;
+}
+
+async function readHookEvents(options: InstallOptions): Promise<HookEventConfig[]> {
+  const manifestPath = path.join(options.pluginTarget, 'hooks', 'hooks.json');
+  const manifest = await readJsonFile<unknown>(manifestPath, {});
+  const events = parseHookEventsManifest(manifest);
+  return events.length > 0 ? events : fallbackHookEvents();
+}
+
+async function writeHooks(options: InstallOptions): Promise<void> {
+  const hooksFile = await readJsonFile<CursorHooksFile>(options.hooksPath, {});
+  if (!hooksFile.version) hooksFile.version = 1;
+  if (!hooksFile.hooks || typeof hooksFile.hooks !== 'object' || Array.isArray(hooksFile.hooks)) {
+    hooksFile.hooks = {};
+  }
+
+  const command = hookCommand(options);
+  const currentHookEvents = await readHookEvents(options);
+
+  for (const [eventName, existing] of Object.entries(hooksFile.hooks)) {
+    if (!Array.isArray(existing)) continue;
+    const unmanagedEntries = existing.filter((entry) => !isManagedHookEntry(entry));
+    if (unmanagedEntries.length > 0) {
+      hooksFile.hooks[eventName] = unmanagedEntries;
+    } else {
+      delete hooksFile.hooks[eventName];
+    }
+  }
+
+  for (const { eventName, timeout } of currentHookEvents) {
+    const existing = hooksFile.hooks[eventName];
+    const entries = Array.isArray(existing) ? existing.filter((entry) => !isManagedHookEntry(entry)) : [];
+    entries.push({ command, timeout });
+    hooksFile.hooks[eventName] = entries;
+  }
+
+  await writeJsonFile(options.hooksPath, hooksFile);
+}
+
+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-cursor installer.',
+    '# Keep this file local because it can contain credentials.',
+    envLine('CURSOR_TLS_REGION', options.region),
+    envLine('CURSOR_TLS_ENDPOINT', options.tlsEndpoint),
+    envLine('CURSOR_TLS_OTEL_ENDPOINT', options.otelEndpoint),
+    envLine('CURSOR_TLS_TRACE_TOPIC_ID', options.traceTopicId),
+    envLine('CURSOR_TLS_API_KEY', options.apiKey),
+    envLine('CURSOR_TLS_AK', options.ak),
+    envLine('CURSOR_TLS_SK', options.sk),
+    envLine('CURSOR_TLS_AUTH_MODE', options.authMode),
+    envLine('CURSOR_TLS_EXPORT_TIMEOUT_MS', options.exportTimeoutMs),
+    envLine('CURSOR_TLS_EXPORT_TIMEOUT_RETRIES', options.exportTimeoutRetries),
+    envLine('CURSOR_TLS_CAPTURE_CONTENT', options.captureContent),
+    envLine('CURSOR_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 writeJsonFile(path.join(options.dataRoot, 'state', 'install.json'), {
+    installed_at: new Date().toISOString(),
+    plugin_name: PLUGIN_NAME,
+    plugin_target: options.pluginTarget,
+    hooks_path: options.hooksPath,
+    env_target: options.envTarget,
+  });
+  await fs.mkdir(path.dirname(options.envTarget), { recursive: true });
+  await fs.writeFile(options.envTarget, buildTlsEnv(options), { mode: 0o600 });
+  return options.envTarget;
+}
+
+function printCompletion({
+  plugin,
+  hooksPath,
+  envTarget,
+}: {
+  plugin: PluginInstallResult;
+  hooksPath: string;
+  envTarget: string | null;
+}): void {
+  console.log('');
+  console.log('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(`  Hooks: ${hooksPath}`);
+  console.log(`  TLS env: ${envTarget || 'skipped'}`);
+  console.log('');
+  console.log('数据访问说明');
+  console.log('安装后，插件会读取会话文件');
+  console.log(
+    '会话文件中的用户请求、模型回复、工具调用记录和 token 用量会整理成诊断数据，上传到你配置的火山引擎 TLS',
+  );
+  console.log('如配置 API Key 或 AK/SK，凭据只写入本机 env 文件，用于上传鉴权');
+  console.log('');
+  console.log('Next steps:');
+  console.log('  1. Restart Cursor.');
+  console.log('  2. Run one Cursor 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);
+  await writeHooks(options);
+  const envTarget = await writeTlsEnv(options);
+  printCompletion({ plugin, hooksPath: options.hooksPath, envTarget });
+}
+
+export { run };