1688-cli 0.1.41 → 0.1.43

package/docs/specs/windows-cli-compatibility.md

@@ -0,0 +1,123 @@
+# Windows CLI Compatibility
+
+This spec defines the compatibility baseline required before `1688-cli` can
+claim normal Windows command-line support.
+
+## Goal
+
+Make the installed CLI and local development workflow work from Windows
+PowerShell and cmd.exe for read-only and daemon-backed commands.
+
+## Scope
+
+- npm package install and build scripts must not depend on Unix shell commands.
+- The daemon IPC path must work on Windows named pipes and avoid collisions
+  between different `BB1688_HOME` roots.
+- Runtime paths, temporary files, and diagnostics must use Node path helpers
+  instead of hard-coded Unix paths where they are part of normal command code.
+- `doctor` fix hints must be executable or meaningful on Windows.
+- README and command docs must show Windows alternatives where Unix examples
+  use `jq`, shell assignment, `/tmp`, or `~/.1688`.
+- Deterministic tests must cover the Windows-specific path and hint logic.
+- CI/package verification must include a Windows-compatible build and smoke
+  path, or document the exact manual Windows checks when CI is not available
+  in the current environment.
+
+## Non-Goals
+
+- Do not bypass 1688 login, slider verification, or risk control.
+- Do not automate Windows UI interaction beyond Playwright's existing browser
+  launch behavior.
+- Do not guarantee live 1688 network/search success in CI; CI checks should be
+  deterministic and use `doctor --no-launch` unless a real account/session is
+  explicitly supplied.
+- Do not change public JSON contracts except by additive diagnostic fields.
+- Do not add a new installer, native binary, or Windows service wrapper.
+
+## Behavior Contract
+
+### Build And Install
+
+`pnpm build` must run on Windows, macOS, and Linux. Any executable-bit fix must
+be implemented in Node and become a no-op on Windows.
+
+`scripts/postinstall.mjs` must:
+
+- locate the daemon pid file under `BB1688_HOME` when set
+- detect Windows Chrome install paths
+- invoke `npx.cmd` on Windows and `npx` elsewhere
+- print retry commands that are valid for the current platform
+
+### Daemon IPC
+
+Unix-like platforms continue to use `<BB1688_HOME>/daemon.sock`.
+
+Windows must use a named pipe:
+
+```text
+\\.\pipe\1688-cli-daemon-<stable-root-hash>
+```
+
+The hash must be stable for a given `BB1688_HOME`/default root and different
+for different roots so tests, profiles, and concurrent users do not collide.
+
+### Diagnostics
+
+`1688 doctor` must emit platform-appropriate fix hints:
+
+- Unix-like stale lock: `rm -rf "..."`
+- Windows stale lock: `Remove-Item -Recurse -Force "..."`
+- Unix-like writable-directory issue: `chmod u+w "..."`
+- Windows writable-directory issue: explain to grant write permission or choose
+  another `BB1688_HOME`
+
+The daemon protocol documentation and README must not describe the daemon as
+Unix-only.
+
+### Documentation
+
+README and command docs must include:
+
+- PowerShell examples using built-in `--get`/`--pick` instead of requiring `jq`
+- Windows output paths such as `$env:TEMP\suppliers.csv`
+- Windows local state paths using `%USERPROFILE%\.1688` or `$env:USERPROFILE`
+- named pipe note for daemon IPC on Windows
+
+## Acceptance Criteria
+
+- `pnpm build` succeeds without requiring `chmod` from the shell.
+- Unit tests cover Windows named pipe generation and platform-specific doctor
+  hints.
+- `pnpm test:unit` passes.
+- `pnpm agent-verify` passes.
+- `npm pack --dry-run` succeeds.
+- README and `docs/COMMANDS.md` no longer present Unix-only examples as the
+  only way to use JSON, output files, or local paths.
+- Manual Windows smoke checklist is documented:
+  - `npm i -g 1688-cli`
+  - `1688 --version`
+  - `1688 doctor --no-launch --json`
+  - `1688 daemon start`
+  - `1688 daemon status --json`
+  - `1688 daemon stop`
+  - `1688 search 雨伞 --max 1 --json`
+  - `1688 supplier search 键盘 --max 1 --json`
+
+## Verification Signals
+
+- Focused tests:
+  - `tests/paths.test.ts`
+  - `tests/doctor.test.ts` or existing doctor tests
+- Package checks:
+  - `pnpm build`
+  - `pnpm test:unit`
+  - `pnpm agent-verify`
+  - `npm pack --dry-run`
+- Manual Windows smoke checks listed above when a Windows machine/session is
+  available.
+
+## Open Questions
+
+- Whether to add GitHub Actions `windows-latest` is a repository operations
+  decision. The code/docs work should make that job straightforward, but adding
+  CI config is not required unless the repository already uses GitHub Actions.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "1688-cli",
-  "version": "0.1.41",
-  "description": "1688.com CLI for humans, Codex, and Claude Code. Sourcing (search / image-search / offer / inquire) and orders (list / detail / logistics / seller chat).",
+  "version": "0.1.43",
+  "description": "1688.com CLI for humans, Codex, and Claude Code. Product search, supplier scraper/research, inquiry, cart, orders, logistics, and seller chat.",
   "license": "MIT",
   "author": "nobodyjack",
   "homepage": "https://github.com/superjack2050/1688-cli#readme",
@@ -22,6 +22,11 @@
     "claude-code",
     "codex",
     "automation",
+    "scraper",
+    "supplier-scraper",
+    "supplier-search",
+    "product-scraper",
+    "sourcing",
     "ecommerce",
     "procurement",
     "playwright",
@@ -36,7 +41,13 @@
   "files": [
     "dist",
     "scripts/postinstall.mjs",
+    "scripts/fix_bin_mode.mjs",
+    "scripts/generate_agent_context.mjs",
+    "scripts/check_agent_map.mjs",
+    "scripts/check_release.mjs",
+    "docs",
     "AGENTS.md",
+    "ARCHITECTURE.md",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"
@@ -46,11 +57,17 @@
   },
   "scripts": {
     "dev": "tsx src/cli.ts",
-    "build": "tsc -p tsconfig.json && chmod +x dist/cli.js",
+    "build": "tsc -p tsconfig.json && node scripts/fix_bin_mode.mjs",
     "test": "vitest run",
+    "test:unit": "vitest run --exclude tests/doctor-live.test.ts",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
-    "prepublishOnly": "pnpm build",
+    "agent-context": "node scripts/generate_agent_context.mjs",
+    "docs-check": "node scripts/generate_agent_context.mjs --check",
+    "agent-map-check": "node scripts/check_agent_map.mjs",
+    "release-check": "node scripts/check_release.mjs",
+    "agent-verify": "pnpm typecheck && pnpm test:unit && pnpm docs-check && pnpm agent-map-check && pnpm release-check",
+    "prepublishOnly": "pnpm release-check && pnpm build",
     "postinstall": "node scripts/postinstall.mjs"
   },
   "dependencies": {

package/scripts/check_agent_map.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+async function read(relPath) {
+  return fs.readFile(path.join(root, relPath), 'utf8');
+}
+
+async function exists(relPath) {
+  try {
+    await fs.access(path.join(root, relPath));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const requiredFiles = [
+  'AGENTS.md',
+  'ARCHITECTURE.md',
+  'docs/AGENT_WORKING_PRINCIPLES.md',
+  'docs/README.md',
+  'docs/WORKFLOW.md',
+  'docs/COMMANDS.md',
+  'docs/JSON_CONTRACTS.md',
+  'docs/SAFETY.md',
+  'docs/RELIABILITY.md',
+  'docs/QUALITY_SCORE.md',
+  'docs/FEATURES.md',
+  'docs/specs/sourcing-research.md',
+  'docs/specs/seller-im.md',
+  'docs/specs/checkout-and-orders.md',
+  'docs/playbooks/add-command.md',
+  'docs/playbooks/change-json-output.md',
+  'docs/playbooks/debug-risk-control.md',
+  'docs/playbooks/add-mtop-capture.md',
+  'docs/playbooks/update-cli-release.md',
+  'docs/records/release-omissions.md',
+  'docs/generated/command-index.md',
+  'docs/generated/module-map.md',
+  'docs/generated/test-index.md',
+  'docs/generated/json-shapes.md',
+];
+
+const missing = [];
+for (const file of requiredFiles) {
+  if (!(await exists(file))) missing.push(file);
+}
+
+const failures = [];
+if (missing.length) failures.push(`Missing files: ${missing.join(', ')}`);
+
+const agents = await read('AGENTS.md').catch(() => '');
+if (!agents.includes('pnpm agent-verify'))
+  failures.push('AGENTS.md must mention pnpm agent-verify.');
+if (!agents.includes('docs/playbooks'))
+  failures.push('AGENTS.md must route work to docs/playbooks.');
+if (!agents.includes('docs/AGENT_WORKING_PRINCIPLES.md'))
+  failures.push('AGENTS.md must link docs/AGENT_WORKING_PRINCIPLES.md.');
+if (agents.split('\n').length > 220)
+  failures.push('AGENTS.md should stay short (<= 220 lines).');
+
+const pkg = JSON.parse(await read('package.json'));
+for (const scriptName of ['agent-context', 'docs-check', 'agent-map-check', 'release-check', 'agent-verify']) {
+  if (!pkg.scripts?.[scriptName]) failures.push(`package.json missing script: ${scriptName}`);
+}
+
+const docsReadme = await read('docs/README.md').catch(() => '');
+for (const needle of [
+  'AGENT_WORKING_PRINCIPLES.md',
+  'COMMANDS.md',
+  'JSON_CONTRACTS.md',
+  'SAFETY.md',
+  'generated/',
+]) {
+  if (!docsReadme.includes(needle)) failures.push(`docs/README.md must link ${needle}.`);
+}
+
+if (failures.length) {
+  console.error(failures.join('\n'));
+  process.exit(1);
+}
+
+console.log('Agent map structure looks good.');

package/scripts/check_release.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+async function readJson(relPath) {
+  return JSON.parse(await fs.readFile(path.join(root, relPath), 'utf8'));
+}
+
+async function read(relPath) {
+  return fs.readFile(path.join(root, relPath), 'utf8');
+}
+
+const pkg = await readJson('package.json');
+const changelog = await read('CHANGELOG.md');
+
+const version = pkg.version;
+const releaseHeading = new RegExp(`^## \\[${version.replaceAll('.', '\\.')}\\] - \\d{4}-\\d{2}-\\d{2}$`, 'm');
+const failures = [];
+
+if (!releaseHeading.test(changelog)) {
+  failures.push(`CHANGELOG.md missing release heading for package version ${version}.`);
+}
+
+if (!pkg.files?.includes('CHANGELOG.md')) {
+  failures.push('package.json files must include CHANGELOG.md.');
+}
+
+if (!pkg.scripts?.['release-check']) {
+  failures.push('package.json missing script: release-check.');
+}
+
+if (failures.length) {
+  console.error(failures.join('\n'));
+  process.exit(1);
+}
+
+console.log(`Release metadata looks good for ${pkg.name}@${version}.`);

package/scripts/fix_bin_mode.mjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+export async function fixBinMode({
+  platform = process.platform,
+  target = path.join('dist', 'cli.js'),
+} = {}) {
+  if (platform === 'win32') {
+    return { changed: false, reason: 'windows-noop', target };
+  }
+  await fs.chmod(target, 0o755);
+  return { changed: true, reason: 'chmod-755', target };
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  await fixBinMode();
+}

package/scripts/generate_agent_context.mjs

@@ -0,0 +1,253 @@
+#!/usr/bin/env node
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const outDir = path.join(root, 'docs', 'generated');
+const checkOnly = process.argv.includes('--check');
+
+const rel = (p) => path.relative(root, p).replaceAll(path.sep, '/');
+const read = (p) => fs.readFile(path.join(root, p), 'utf8');
+
+async function exists(p) {
+  try {
+    await fs.access(path.join(root, p));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function walk(dir, predicate = () => true) {
+  const abs = path.join(root, dir);
+  const out = [];
+  async function visit(current) {
+    const entries = await fs.readdir(current, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name === 'node_modules' || entry.name === '.git') continue;
+      const p = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        await visit(p);
+      } else if (predicate(p)) {
+        out.push(p);
+      }
+    }
+  }
+  if (await exists(dir)) await visit(abs);
+  return out.sort((a, b) => rel(a).localeCompare(rel(b)));
+}
+
+function header(title) {
+  return `# ${title}\n\n_Generated by \`scripts/generate_agent_context.mjs\`._\n\n`;
+}
+
+function cleanDescription(raw) {
+  if (!raw) return '-';
+  return raw
+    .replace(/[`'"]/g, '')
+    .replace(/\s*\+\s*/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .replace(/\|/g, '\\|') || '-';
+}
+
+function compactList(items) {
+  return items.length ? items.map((x) => `\`${x}\``).join('<br>') : '-';
+}
+
+async function commandIndex() {
+  const cli = await read('src/cli.ts');
+  const re =
+    /(?:(?:const\s+([A-Za-z0-9_]+)\s*=\s*)?([A-Za-z0-9_]+)\s*\n\s*\.command\('([^']+)'\))/g;
+  const matches = [...cli.matchAll(re)];
+  const varToCommand = new Map();
+  const rows = [];
+
+  for (let i = 0; i < matches.length; i++) {
+    const m = matches[i];
+    const assignedVar = m[1];
+    const receiver = m[2];
+    const command = m[3];
+    const start = m.index ?? 0;
+    const end = matches[i + 1]?.index ?? cli.length;
+    const block = cli.slice(start, end);
+    const parent = receiver === 'program' ? '' : varToCommand.get(receiver) ?? receiver;
+    const full = parent ? `${parent} ${command}` : command;
+    if (assignedVar) varToCommand.set(assignedVar, full);
+
+    const descRaw = block.match(/\.description\(([\s\S]*?)\)\s*(?:\.|\n)/)?.[1];
+    const args = [...block.matchAll(/\.argument\(\s*(['"`])([^'"`]+)\1/g)].map(
+      (x) => x[2],
+    );
+    const opts = [
+      ...block.matchAll(/\.(?:requiredOption|option)\(\s*(['"`])([^'"`]+)\1/g),
+    ].map((x) => x[2]);
+    const source = block.match(/import\('\.\/commands\/([^']+)\.js'\)/)?.[1];
+    rows.push({
+      command: full,
+      source: source ? `src/commands/${source}.ts` : '-',
+      args,
+      opts,
+      description: cleanDescription(descRaw),
+    });
+  }
+
+  let out = header('Command Index');
+  out += '| Command | Source | Arguments | Options | Description |\n';
+  out += '|---|---|---|---|---|\n';
+  for (const row of rows) {
+    out += `| \`${row.command}\` | ${row.source === '-' ? '-' : `\`${row.source}\``} | ${compactList(
+      row.args,
+    )} | ${compactList(row.opts)} | ${row.description} |\n`;
+  }
+  return out;
+}
+
+async function moduleMap() {
+  const files = await walk('src', (p) => p.endsWith('.ts'));
+  const tests = await walk('tests', (p) => p.endsWith('.test.ts') || p.endsWith('.spec.ts'));
+  const dirs = new Map();
+  for (const file of files) {
+    const r = rel(file);
+    const parts = r.split('/');
+    const dir = parts.length > 2 ? `${parts[0]}/${parts[1]}` : parts[0];
+    const entry = dirs.get(dir) ?? { files: 0, tests: 0, notes: '-' };
+    entry.files++;
+    dirs.set(dir, entry);
+  }
+  for (const file of tests) {
+    const content = await fs.readFile(file, 'utf8');
+    const target = content.match(/from ['"]\.\.\/src\/([^/'"]+)/)?.[1];
+    if (target) {
+      const key = `src/${target}`;
+      const entry = dirs.get(key) ?? { files: 0, tests: 0, notes: '-' };
+      entry.tests++;
+      dirs.set(key, entry);
+    }
+  }
+
+  const notes = {
+    'src/commands': 'command executors and renderers',
+    'src/session': 'browser/session automation helpers',
+    'src/daemon': 'background daemon client/server/protocol',
+    'src/io': 'output, prompts, and errors',
+    'src/auth': 'login/session/cookie helpers',
+    'src/util': 'shared utilities',
+  };
+
+  let out = header('Module Map');
+  out += '| Directory | Source Files | Related Tests | Notes |\n';
+  out += '|---|---:|---:|---|\n';
+  for (const dir of [...dirs.keys()].sort()) {
+    const entry = dirs.get(dir);
+    out += `| \`${dir}\` | ${entry.files} | ${entry.tests} | ${notes[dir] ?? entry.notes} |\n`;
+  }
+  return out;
+}
+
+async function testIndex() {
+  const tests = await walk('tests', (p) => p.endsWith('.test.ts') || p.endsWith('.spec.ts'));
+  let out = header('Test Index');
+  out += '| Test File | Focus | Risk Notes |\n';
+  out += '|---|---|---|\n';
+  for (const file of tests) {
+    const content = await fs.readFile(file, 'utf8');
+    const name = path.basename(file).replace(/\.(test|spec)\.ts$/, '');
+    const risks = [];
+    if (/live|doctor-live|process\.env|BB1688|1688\s/.test(content + name))
+      risks.push('live/session-sensitive');
+    if (/playwright|BrowserContext|Page|page-state|risk-control/i.test(content))
+      risks.push('browser/page-state');
+    if (/fixture|jsonp|mtop|capture/i.test(content)) risks.push('fixture/parser');
+    out += `| \`${rel(file)}\` | ${name} | ${risks.join(', ') || '-'} |\n`;
+  }
+  return out;
+}
+
+function extractInterfaces(source, file) {
+  const lines = source.split('\n');
+  const interfaces = [];
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(/^export interface ([A-Za-z0-9_]+)/);
+    if (!m) continue;
+    const name = m[1];
+    const keep =
+      /(Args|Opts|Result|Offer|Message|CartItem|Order|Sku|Price|Attribute|Package)/.test(
+        name,
+      );
+    if (!keep) continue;
+
+    const body = [];
+    let depth = 0;
+    for (let j = i; j < lines.length; j++) {
+      const line = lines[j];
+      if (j > i) body.push(line);
+      depth += (line.match(/\{/g) ?? []).length;
+      depth -= (line.match(/\}/g) ?? []).length;
+      if (j > i && depth <= 0) break;
+    }
+    const fields = body
+      .map((line) => line.trim())
+      .filter((line) => /^[A-Za-z0-9_?]+:/.test(line) || /^\/\*\*/.test(line))
+      .slice(0, 14)
+      .map((line) => line.replace(/\|/g, '\\|'));
+    interfaces.push({ name, file, fields });
+  }
+  return interfaces;
+}
+
+async function jsonShapes() {
+  const files = await walk('src', (p) => p.endsWith('.ts'));
+  const interfaces = [];
+  for (const file of files) {
+    const source = await fs.readFile(file, 'utf8');
+    interfaces.push(...extractInterfaces(source, rel(file)));
+  }
+
+  let out = header('JSON Shapes');
+  out +=
+    'This is a heuristic index of exported TypeScript interfaces that are likely to matter for agent-facing JSON.\n\n';
+  out += '| Interface | File | Notable Fields |\n';
+  out += '|---|---|---|\n';
+  for (const it of interfaces.sort((a, b) => a.file.localeCompare(b.file) || a.name.localeCompare(b.name))) {
+    out += `| \`${it.name}\` | \`${it.file}\` | ${it.fields.length ? it.fields.map((x) => `\`${x}\``).join('<br>') : '-'} |\n`;
+  }
+  return out;
+}
+
+const outputs = new Map([
+  ['command-index.md', await commandIndex()],
+  ['module-map.md', await moduleMap()],
+  ['test-index.md', await testIndex()],
+  ['json-shapes.md', await jsonShapes()],
+]);
+
+if (checkOnly) {
+  const mismatches = [];
+  for (const [name, content] of outputs) {
+    const target = path.join(outDir, name);
+    let current = '';
+    try {
+      current = await fs.readFile(target, 'utf8');
+    } catch {
+      mismatches.push(name);
+      continue;
+    }
+    if (current !== content) mismatches.push(name);
+  }
+  if (mismatches.length) {
+    console.error(
+      `Generated agent context is stale: ${mismatches.join(', ')}. Run pnpm agent-context.`,
+    );
+    process.exit(1);
+  }
+  console.log('Generated agent context is fresh.');
+} else {
+  await fs.mkdir(outDir, { recursive: true });
+  for (const [name, content] of outputs) {
+    await fs.writeFile(path.join(outDir, name), content);
+  }
+  console.log(`Generated agent context files in ${rel(outDir)}`);
+}
+

package/scripts/postinstall.mjs

@@ -21,7 +21,10 @@ if (process.env.CI || process.env.BB1688_SKIP_POSTINSTALL) {
 // Otherwise the old daemon keeps serving stale code until the user runs
 // `1688 daemon stop` manually after every upgrade.
 try {
-  const pidFile = path.join(os.homedir(), '.1688', 'daemon.pid');
+  const pidFile = path.join(
+    process.env.BB1688_HOME ?? path.join(os.homedir(), '.1688'),
+    'daemon.pid',
+  );
   if (fs.existsSync(pidFile)) {
     const pid = parseInt(fs.readFileSync(pidFile, 'utf8').trim(), 10);
     if (Number.isInteger(pid) && pid > 0) {
@@ -140,19 +143,24 @@ console.log(
 const env = { ...process.env };
 if (downloadHost) env.PLAYWRIGHT_DOWNLOAD_HOST = downloadHost;
 
-const res = spawnSync('npx', ['playwright', 'install', 'chromium'], {
+const npxCmd = process.platform === 'win32' ? 'npx.cmd' : 'npx';
+const res = spawnSync(npxCmd, ['playwright', 'install', 'chromium'], {
   stdio: 'inherit',
   env,
 });
 
 if (res.status !== 0) {
+  const retryCommand =
+    process.platform === 'win32'
+      ? '             $env:PLAYWRIGHT_DOWNLOAD_HOST="https://npmmirror.com/mirrors/playwright"; npx playwright install chromium\n'
+      : '             PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright \\\n' +
+        '               npx playwright install chromium\n';
   console.log(
     '\n1688-cli: Chromium download failed (non-fatal).\n' +
       '          Try running manually:\n' +
       '          1) Install Chrome from https://www.google.com/chrome/ (recommended), or\n' +
       '          2) Force-retry with mirror:\n' +
-      '             PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright \\\n' +
-      '               npx playwright install chromium\n',
+      retryCommand,
   );
 }
 process.exit(0);