@skills-store/rednote 0.1.0

package/README.md

@@ -0,0 +1,35 @@
+# rednote
+
+A Xiaohongshu (RED) automation CLI.
+
+## Run with npx
+
+```bash
+npx -y @skills-store/rednote browser list
+npx -y @skills-store/rednote browser create --name seller-main --browser chrome
+npx -y @skills-store/rednote browser connect --instance seller-main
+npx -y @skills-store/rednote login --instance seller-main
+npx -y @skills-store/rednote search --instance seller-main --keyword 护肤
+npx -y @skills-store/rednote get-feed-detail --instance seller-main --url "https://www.xiaohongshu.com/explore/<id>?xsec_token=<token>"
+npx -y @skills-store/rednote get-profile --instance seller-main --id USER_ID
+```
+
+## Install globally
+
+```bash
+npm install -g @skills-store/rednote
+```
+
+## Storage
+
+The CLI stores custom browser instances and metadata under:
+
+```text
+~/.skills-router/rednote/instances
+```
+
+Run this to inspect the current environment and exact resolved paths:
+
+```bash
+npx -y @skills-store/rednote env
+```

package/bin/rednote.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const entry = path.resolve(__dirname, '../scripts/index.ts');
+
+const child = spawn(process.execPath, ['--experimental-strip-types', entry, ...process.argv.slice(2)], {
+  stdio: 'inherit',
+  env: process.env,
+});
+
+child.on('exit', (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+
+  process.exit(code ?? 1);
+});
+
+child.on('error', (error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@skills-store/rednote",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "bin": {
+    "rednote": "./bin/rednote.js"
+  },
+  "scripts": {
+    "rednote": "node --experimental-strip-types ./scripts/index.ts",
+    "browser": "node --experimental-strip-types ./scripts/browser/index.ts",
+    "env": "node --experimental-strip-types ./scripts/rednote/env.ts",
+    "status": "node --experimental-strip-types ./scripts/rednote/status.ts",
+    "check-login": "node --experimental-strip-types ./scripts/rednote/checkLogin.ts",
+    "login": "node --experimental-strip-types ./scripts/rednote/login.ts",
+    "home": "node --experimental-strip-types ./scripts/rednote/home.ts",
+    "search": "node --experimental-strip-types ./scripts/rednote/search.ts",
+    "get-feed-detail": "node --experimental-strip-types ./scripts/rednote/getFeedDetail.ts",
+    "get-profile": "node --experimental-strip-types ./scripts/rednote/getProfile.ts",
+    "bun:rednote": "bun ./scripts/index.ts",
+    "bun:browser": "bun ./scripts/browser/index.ts",
+    "bun:env": "bun ./scripts/rednote/env.ts",
+    "bun:status": "bun ./scripts/rednote/status.ts",
+    "bun:check-login": "bun ./scripts/rednote/checkLogin.ts",
+    "bun:login": "bun ./scripts/rednote/login.ts",
+    "bun:home": "bun ./scripts/rednote/home.ts",
+    "bun:search": "bun ./scripts/rednote/search.ts",
+    "bun:get-feed-detail": "bun ./scripts/rednote/getFeedDetail.ts",
+    "bun:get-profile": "bun ./scripts/rednote/getProfile.ts"
+  },
+  "dependencies": {
+    "cheerio": "^1.2.0",
+    "chrome-paths": "^1.0.1",
+    "edge-paths": "^3.0.5",
+    "pid-port": "^1.0.2",
+    "playwright-core": "^1.52.0",
+    "ps-list": "^8.1.1"
+  },
+  "engines": {
+    "node": ">=22.6.0",
+    "bun": ">=1.0.0"
+  },
+  "description": "Xiaohongshu automation CLI for Skills Router",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "bin/rednote.js",
+    "scripts",
+    "README.md",
+    "package.json",
+    "tsconfig.json"
+  ]
+}

package/scripts/browser/connect-browser.ts

@@ -0,0 +1,218 @@
+#!/usr/bin/env -S node --experimental-strip-types
+
+import {
+  closeProcessesByPid,
+  findSpec,
+  getCdpWebSocketUrl,
+  getPidsListeningOnPort,
+  inspectBrowserInstance,
+  getRandomAvailablePort,
+  launchBrowser,
+  removeLockFiles,
+  readInstanceStore,
+  resolveExecutablePath,
+  resolveUserDataDir,
+  type ConnectBrowserOptions,
+  type ConnectBrowserResult,
+  type LastConnectInfo,
+  updateInstanceRemoteDebuggingPort,
+  updateLastConnect,
+  validateInstanceName,
+  waitForCdpReady,
+  waitForPortToClose,
+} from '../utils/browser-core.ts';
+import {
+  parseBrowserCliArgs,
+  printConnectBrowserHelp,
+  printJson,
+  runCli,
+  debugLog,
+  type BrowserCliValues,
+} from '../utils/browser-cli.ts';
+
+
+async function resolveBrowserPid(remoteDebuggingPort: number, detectedPid: number | null) {
+  if (detectedPid) {
+    return detectedPid;
+  }
+
+  const portPids = await getPidsListeningOnPort(remoteDebuggingPort);
+  return portPids[0] ?? null;
+}
+
+export async function resolveConnectOptions(options: ConnectBrowserOptions & { instanceName?: string }) {
+  if (!options.instanceName) {
+    return {
+      connectOptions: options,
+      lastConnect:
+        options.userDataDir
+          ? null
+          : {
+              scope: 'default',
+              name: options.browser ?? 'chrome',
+              browser: options.browser ?? 'chrome',
+            } satisfies LastConnectInfo,
+    };
+  }
+
+  if (options.userDataDir) {
+    throw new Error('Do not combine --instance with --user-data-dir');
+  }
+
+  if (options.browser) {
+    throw new Error('Do not combine --instance with --browser');
+  }
+
+  const store = readInstanceStore();
+  const instanceName = validateInstanceName(options.instanceName);
+  const persisted = store.instances.find((instance) => instance.name === instanceName);
+  if (!persisted) {
+    throw new Error(`Unknown instance: ${instanceName}`);
+  }
+
+  let remoteDebuggingPort = options.remoteDebuggingPort ?? persisted.remoteDebuggingPort;
+  if (!remoteDebuggingPort) {
+    remoteDebuggingPort = await getRandomAvailablePort();
+    updateInstanceRemoteDebuggingPort(instanceName, remoteDebuggingPort);
+  }
+
+  return {
+    connectOptions: {
+      ...options,
+      browser: persisted.browser,
+      userDataDir: persisted.userDataDir,
+      remoteDebuggingPort,
+    } satisfies ConnectBrowserOptions,
+    lastConnect: {
+      scope: 'custom',
+      name: persisted.name,
+      browser: persisted.browser,
+    } satisfies LastConnectInfo,
+  };
+}
+
+export async function initBrowser(options: ConnectBrowserOptions = {}): Promise<ConnectBrowserResult> {
+  debugLog('initBrowser', 'start', { options });
+  const browserType = options.browser ?? 'chrome';
+  const spec = findSpec(browserType);
+  const executablePath = options.executablePath || resolveExecutablePath(spec);
+  if (!executablePath) {
+    throw new Error(`No executable found for ${spec.displayName}`);
+  }
+
+  const userDataDir = resolveUserDataDir(spec, options);
+  const remoteDebuggingPort = options.remoteDebuggingPort ?? 9222;
+  const connectTimeoutMs = options.connectTimeoutMs ?? 15_000;
+  const killTimeoutMs = options.killTimeoutMs ?? 8_000;
+  const startupUrl = options.startupUrl ?? 'about:blank';
+
+  const detectedInstance = await inspectBrowserInstance(spec, executablePath, userDataDir);
+  debugLog('initBrowser', 'inspected instance', {
+    browserType,
+    executablePath,
+    userDataDir,
+    remoteDebuggingPort,
+    detectedInstance,
+  });
+  const closedPidSet = new Set<number>();
+
+  const existingWsUrl = await getCdpWebSocketUrl(remoteDebuggingPort);
+  debugLog('initBrowser', 'checked existing ws url', { remoteDebuggingPort, existingWsUrl });
+  if (existingWsUrl) {
+    debugLog('initBrowser', 'reusing existing ws url', { remoteDebuggingPort, existingWsUrl });
+    return {
+      ok: true,
+      type: spec.type,
+      executablePath,
+      userDataDir,
+      remoteDebuggingPort,
+      wsUrl: existingWsUrl,
+      pid: await resolveBrowserPid(remoteDebuggingPort, detectedInstance.pid),
+    };
+  }
+
+  if (detectedInstance.inUse && detectedInstance.remotePort === null) {
+    if (!options.force) {
+      throw new Error(
+        `Browser profile is already in use without a remote debugging port. Re-run with --force to safely close it first: ${detectedInstance.userDataDir}`,
+      );
+    }
+
+    if (detectedInstance.pids.length === 0) {
+      throw new Error(
+        `Browser profile is in use but no running browser PID was found for safe shutdown: ${detectedInstance.userDataDir}`,
+      );
+    }
+  }
+
+  if (detectedInstance.inUse && detectedInstance.pids.length > 0) {
+    debugLog('initBrowser', 'detected in-use profile, closing existing processes', {
+      pids: detectedInstance.pids,
+      killTimeoutMs,
+      remoteDebuggingPort,
+    });
+    for (const pid of await closeProcessesByPid(detectedInstance.pids, killTimeoutMs)) {
+      closedPidSet.add(pid);
+    }
+    await waitForPortToClose(remoteDebuggingPort, killTimeoutMs);
+  } else if (detectedInstance.staleLock) {
+    if (!options.force) {
+      throw new Error(`Profile is locked by stale files: ${detectedInstance.lockFiles.join(', ')}`);
+    }
+
+    removeLockFiles(detectedInstance.lockFiles);
+  }
+
+  const launched = await launchBrowser(spec, executablePath, userDataDir, remoteDebuggingPort, startupUrl);
+  debugLog('initBrowser', 'launched browser', { remoteDebuggingPort, pid: launched.pid ?? null, startupUrl });
+
+  const wsUrl = await waitForCdpReady(remoteDebuggingPort, connectTimeoutMs);
+  debugLog('initBrowser', 'waited for cdp ready', { remoteDebuggingPort, connectTimeoutMs, wsUrl });
+  if (!wsUrl) {
+    throw new Error(`CDP did not become available on port ${remoteDebuggingPort}`);
+  }
+
+  return {
+    ok: true,
+    type: spec.type,
+    executablePath,
+    userDataDir,
+    remoteDebuggingPort,
+    wsUrl,
+    pid: launched.pid ?? await resolveBrowserPid(remoteDebuggingPort, detectedInstance.pid),
+  };
+}
+
+export async function runConnectBrowserCommand(values: BrowserCliValues) {
+  const resolved = await resolveConnectOptions({
+    browser: values.browser,
+    instanceName: values.instance,
+    executablePath: values['executable-path'],
+    userDataDir: values['user-data-dir'],
+    force: values.force,
+    remoteDebuggingPort: values.port ? Number(values.port) : undefined,
+    connectTimeoutMs: values.timeout ? Number(values.timeout) : undefined,
+    killTimeoutMs: values['kill-timeout'] ? Number(values['kill-timeout']) : undefined,
+    startupUrl: values['startup-url'],
+  });
+  const result = await initBrowser(resolved.connectOptions);
+
+  if (resolved.lastConnect) {
+    updateLastConnect(resolved.lastConnect);
+  }
+
+  printJson(result);
+}
+
+async function main() {
+  const { values } = parseBrowserCliArgs(process.argv.slice(2));
+
+  if (values.help) {
+    printConnectBrowserHelp();
+    return;
+  }
+
+  await runConnectBrowserCommand(values);
+}
+
+runCli(import.meta.url, main);

package/scripts/browser/create-browser.ts

@@ -0,0 +1,81 @@
+#!/usr/bin/env -S node --experimental-strip-types
+
+import {
+  customInstanceUserDataDir,
+  ensureDir,
+  isDefaultInstanceName,
+  readInstanceStore,
+  type CreateInstanceOptions,
+  type CreateInstanceResult,
+  type PersistedInstance,
+  validateInstanceName,
+  writeInstanceStore,
+} from '../utils/browser-core.ts';
+import {
+  parseBrowserCliArgs,
+  printCreateBrowserHelp,
+  printJson,
+  runCli,
+  type BrowserCliValues,
+} from '../utils/browser-cli.ts';
+
+export function createBrowserInstance(options: CreateInstanceOptions): CreateInstanceResult {
+  const store = readInstanceStore();
+  const name = validateInstanceName(options.name);
+  const browser = options.browser ?? 'chrome';
+
+  if (isDefaultInstanceName(name)) {
+    throw new Error(`Instance name is reserved for a default browser: ${name}`);
+  }
+
+  if (store.instances.some((instance) => instance.name === name)) {
+    throw new Error(`Instance already exists: ${name}`);
+  }
+
+  const instance: PersistedInstance = {
+    name,
+    browser,
+    userDataDir: ensureDir(customInstanceUserDataDir(name)),
+    createdAt: new Date().toISOString(),
+    remoteDebuggingPort:
+      typeof options.remoteDebuggingPort === 'number' && Number.isInteger(options.remoteDebuggingPort) && options.remoteDebuggingPort > 0
+        ? options.remoteDebuggingPort
+        : undefined,
+  };
+
+  writeInstanceStore({
+    ...store,
+    instances: [...store.instances, instance],
+  });
+
+  return {
+    ok: true,
+    instance,
+  };
+}
+
+export function runCreateBrowserCommand(values: BrowserCliValues) {
+  if (!values.name) {
+    throw new Error('Missing required option: --name');
+  }
+
+  const result = createBrowserInstance({
+    name: values.name,
+    browser: values.browser,
+    remoteDebuggingPort: values.port ? Number(values.port) : undefined,
+  });
+  printJson(result);
+}
+
+async function main() {
+  const { values } = parseBrowserCliArgs(process.argv.slice(2));
+
+  if (values.help) {
+    printCreateBrowserHelp();
+    return;
+  }
+
+  runCreateBrowserCommand(values);
+}
+
+runCli(import.meta.url, main);

package/scripts/browser/index.ts

@@ -0,0 +1,49 @@
+#!/usr/bin/env -S node --experimental-strip-types
+
+import {
+  parseBrowserCliArgs,
+  printInitBrowserHelp,
+  runCli,
+} from '../utils/browser-cli.ts';
+
+export async function runBrowserCli(argv: string[] = process.argv.slice(2)) {
+  const { values, positionals } = parseBrowserCliArgs(argv);
+  const command = positionals[0] || 'list';
+
+  if (values.help || command === 'help') {
+    printInitBrowserHelp();
+    return;
+  }
+
+  if (command === 'list') {
+    const { runListBrowserCommand } = await import('./list-browser.ts');
+    await runListBrowserCommand(values);
+    return;
+  }
+
+  if (command === 'create') {
+    const { runCreateBrowserCommand } = await import('./create-browser.ts');
+    runCreateBrowserCommand(values);
+    return;
+  }
+
+  if (command === 'remove') {
+    const { runRemoveBrowserCommand } = await import('./remove-browser.ts');
+    await runRemoveBrowserCommand(values);
+    return;
+  }
+
+  if (command === 'connect') {
+    const { runConnectBrowserCommand } = await import('./connect-browser.ts');
+    await runConnectBrowserCommand(values);
+    return;
+  }
+
+  throw new Error(`Unknown browser command: ${command}`);
+}
+
+async function main() {
+  await runBrowserCli();
+}
+
+runCli(import.meta.url, main);

package/scripts/browser/list-browser.ts

@@ -0,0 +1,74 @@
+#!/usr/bin/env -S node --experimental-strip-types
+
+import {
+  browserSpecs,
+  findSpec,
+  inspectBrowserInstance,
+  isLastConnectMatch,
+  readInstanceStore,
+  toBrowserInstanceInfo,
+  type ListBrowserInstancesResult,
+  type ListedBrowserInstance,
+} from '../utils/browser-core.ts';
+import {
+  parseBrowserCliArgs,
+  printJson,
+  printListBrowserHelp,
+  runCli,
+  type BrowserCliValues,
+} from '../utils/browser-cli.ts';
+
+export async function listBrowserInstances(): Promise<ListBrowserInstancesResult> {
+  const specs = browserSpecs();
+  const store = readInstanceStore();
+  const defaultInstances = await Promise.all(
+    specs.map(async (spec) => {
+      const instance = await inspectBrowserInstance(spec);
+      return {
+        ...toBrowserInstanceInfo(instance),
+        scope: 'default',
+        instanceName: spec.type,
+        createdAt: null,
+        lastConnect: isLastConnectMatch(store.lastConnect, 'default', spec.type, spec.type),
+      } satisfies ListedBrowserInstance;
+    }),
+  );
+  const customInstances = await Promise.all(
+    store.instances.map(async (persisted) => {
+      const spec = findSpec(persisted.browser);
+      const instance = await inspectBrowserInstance(spec, undefined, persisted.userDataDir);
+      return {
+        ...toBrowserInstanceInfo(instance),
+        name: persisted.name,
+        userDataDir: persisted.userDataDir,
+        scope: 'custom',
+        instanceName: persisted.name,
+        createdAt: persisted.createdAt,
+        lastConnect: isLastConnectMatch(store.lastConnect, 'custom', persisted.name, persisted.browser),
+      } satisfies ListedBrowserInstance;
+    }),
+  );
+
+  return {
+    lastConnect: store.lastConnect,
+    instances: [...defaultInstances, ...customInstances],
+  };
+}
+
+export async function runListBrowserCommand(_values?: BrowserCliValues) {
+  const instances = await listBrowserInstances();
+  printJson(instances);
+}
+
+async function main() {
+  const { values } = parseBrowserCliArgs(process.argv.slice(2));
+
+  if (values.help) {
+    printListBrowserHelp();
+    return;
+  }
+
+  await runListBrowserCommand(values);
+}
+
+runCli(import.meta.url, main);

package/scripts/browser/remove-browser.ts

@@ -0,0 +1,109 @@
+#!/usr/bin/env -S node --experimental-strip-types
+
+import fs from 'node:fs';
+import {
+  closeProcessesByPid,
+  customInstanceUserDataDir,
+  exists,
+  findSpec,
+  inspectBrowserInstance,
+  INSTANCES_DIR,
+  isDefaultInstanceName,
+  isSubPath,
+  normalizePath,
+  readInstanceStore,
+  type RemoveInstanceOptions,
+  type RemoveInstanceResult,
+  validateInstanceName,
+  waitForPortToClose,
+  writeInstanceStore,
+} from '../utils/browser-core.ts';
+import {
+  parseBrowserCliArgs,
+  printJson,
+  printRemoveBrowserHelp,
+  runCli,
+  type BrowserCliValues,
+} from '../utils/browser-cli.ts';
+
+export async function removeBrowserInstance(options: RemoveInstanceOptions): Promise<RemoveInstanceResult> {
+  const store = readInstanceStore();
+  const name = validateInstanceName(options.name);
+  if (isDefaultInstanceName(name)) {
+    throw new Error(`Default instance cannot be removed: ${name}`);
+  }
+
+  const instance = store.instances.find((item) => item.name === name);
+  if (!instance) {
+    throw new Error(`Instance not found: ${name}`);
+  }
+
+  const expectedUserDataDir = customInstanceUserDataDir(name);
+  const resolvedUserDataDir = normalizePath(instance.userDataDir);
+  if (!isSubPath(INSTANCES_DIR, resolvedUserDataDir) || normalizePath(expectedUserDataDir) !== resolvedUserDataDir) {
+    throw new Error(`Refusing to remove unexpected instance directory: ${instance.userDataDir}`);
+  }
+
+  const spec = findSpec(instance.browser);
+  const detectedInstance = await inspectBrowserInstance(spec, undefined, resolvedUserDataDir);
+  if (detectedInstance.inUse && !options.force) {
+    throw new Error(`Instance is currently in use. Re-run with --force: ${name}`);
+  }
+
+  const closedPids: number[] = [];
+  if (options.force && detectedInstance.pids.length > 0) {
+    for (const pid of await closeProcessesByPid(detectedInstance.pids, 8_000)) {
+      closedPids.push(pid);
+    }
+
+    if (detectedInstance.remotePort !== null) {
+      await waitForPortToClose(detectedInstance.remotePort, 8_000);
+    }
+  }
+
+  const removedDir = exists(resolvedUserDataDir);
+  fs.rmSync(resolvedUserDataDir, { recursive: true, force: true });
+
+  writeInstanceStore({
+    ...store,
+    lastConnect:
+      store.lastConnect?.scope === 'custom' &&
+      store.lastConnect.name === instance.name &&
+      store.lastConnect.browser === instance.browser
+        ? null
+        : store.lastConnect,
+    instances: store.instances.filter((item) => item.name !== instance.name),
+  });
+
+  return {
+    ok: true,
+    removedInstance: instance,
+    removedDir,
+    closedPids,
+  };
+}
+
+export async function runRemoveBrowserCommand(values: BrowserCliValues) {
+  if (!values.name) {
+    throw new Error('Missing required option: --name');
+  }
+
+  const result = await removeBrowserInstance({
+    name: values.name,
+    force: values.force,
+  });
+  printJson(result);
+}
+
+async function main() {
+  const { values } = parseBrowserCliArgs(process.argv.slice(2));
+
+  if (values.help) {
+    process.stdout.write(`remove-browser\n\nUsage:\n  node --experimental-strip-types ./scripts/browser/remove-browser.ts --name NAME [--force]\n  bun ./scripts/browser/remove-browser.ts --name NAME [--force]\n`);
+    return;
+  }
+
+  await runRemoveBrowserCommand(values);
+}
+
+runCli(import.meta.url, main);