1688-cli 0.1.41 → 0.1.43

package/docs/SAFETY.md

@@ -0,0 +1,99 @@
+# Safety
+
+This tool operates a real 1688 buyer account. Some commands read public or
+account data; others contact sellers, mutate cart state, submit feedback, or
+place orders. Treat write actions as explicit user-authorized operations.
+
+## Exit Codes
+
+| Code | Meaning | Agent behavior |
+|---:|---|---|
+| 0 | Success | Continue. |
+| 2 | Bad invocation | Fix arguments or report the bad input. |
+| 3 | Not logged in / session expired | Tell the user to run `1688 login`; do not loop. |
+| 4 | Risk control / slider verification | Tell the user to rerun once with `--headed`; do not silently retry. |
+| 5 | Another 1688 command is running for the selected profile | Wait only if the task naturally allows it; otherwise report lock busy. |
+| 6 | Chromium missing | Report dependency issue. |
+| 7 | Login wait timeout | Report timeout. |
+| 8 | Login finished but cookies missing | Report login cookie issue. |
+| 9 | Network error | Report or retry only when safe and bounded. |
+| 130 | User canceled | Stop. |
+
+## Login And Logout
+
+- `1688 login` opens a user-interactive QR/browser flow. Only run it when the
+  user explicitly asks to log in.
+- In non-interactive sessions, `1688 login` saves a QR PNG to
+  `~/.1688/login-qr.png` and prints `QR saved as PNG: <path>` on stderr.
+  Surface that file/path to the user and wait for the command to exit.
+- Do not open the raw QR URL in a browser.
+- `1688 logout --yes` destroys the cached session. Do not pass `--yes` without
+  explicit current-turn confirmation.
+
+## Risk Control
+
+- If exit code `4` appears, tell the user to rerun the same command once with
+  `--headed`.
+- The user must solve the slider manually.
+- Do not silently retry the same blocked command.
+
+## Seller Contact
+
+These commands contact real sellers:
+
+```bash
+1688 seller inquire <offerId> <message>
+1688 seller chat <orderId|loginId> <message>
+```
+
+Before sending, show the message and target context unless the user has already
+given an explicit current-turn send instruction.
+
+## Cart Mutations
+
+These commands mutate buyer cart state:
+
+```bash
+1688 cart add <offerId> --sku <skuId> --qty N
+1688 cart remove <cartId>
+```
+
+For agent use, show the offer/SKU/quantity or cart row being changed and run
+only after the user approves that action.
+
+## Checkout Protocol
+
+`1688 checkout confirm` places a real order. It does not pay automatically, but
+it commits the buyer to the seller.
+
+Agent protocol:
+
+1. Run `1688 checkout prepare <cartIds...>`.
+2. Show the full preview: total, items, address, seller, and cart IDs.
+3. Wait for explicit current-turn approval such as "yes, place it" or
+   "下单吧".
+4. Run `1688 checkout confirm <cartIds...> --agent`.
+5. Report the final order ID and URL.
+
+Never run `--agent` without this prepare plus approval cycle. Never infer
+authorization from older messages.
+
+## Feedback Submission
+
+`1688 feedback "<message>"` prepares a GitHub issue URL. That is safe by
+default.
+
+`1688 feedback "<message>" --submit` posts publicly through `gh`. Do not add
+`--submit` unless the user explicitly asks to submit/post the issue.
+
+## Update Awareness
+
+`1688 doctor --no-launch --json` reports version information. Any JSON-mode
+command may also emit an update notice on stderr.
+
+Rules:
+
+- In an interactive session, ask once before running the printed global install
+  command.
+- In non-interactive loops, do not upgrade automatically.
+- After an approved package update, run `1688 daemon reload`.

package/docs/WORKFLOW.md

@@ -0,0 +1,82 @@
+# Workflow
+
+This is the default workflow for AI agents and humans working in this
+repository. Keep it executable and linked to deeper docs.
+
+## Operating Model
+
+- Humans set intent, constraints, priorities, and approval boundaries.
+- Agents read the map, choose the smallest coherent slice, implement, verify,
+  and update durable docs.
+- `AGENTS.md` is the fast entry point; this file is the default operating loop.
+- Playbooks under `docs/playbooks/` hold repeatable task details.
+- ExecPlans under `docs/exec-plans/` hold long-running state that should
+  survive chat history loss.
+
+## Standard Task Brief
+
+Capture or infer these fields before changing code:
+
+```md
+Goal:
+Context:
+Constraints:
+Done when:
+```
+
+Ask the human only when the missing choice changes product behavior, checkout
+safety, data retention, account security, or external write actions.
+
+## New Feature Flow
+
+1. Read `AGENTS.md`, `ARCHITECTURE.md`, `docs/README.md`, and the relevant
+   product spec or playbook.
+2. Locate the owning command/session/daemon/io layer.
+3. For complex work, create or update an ExecPlan in
+   `docs/exec-plans/active/`.
+4. Implement one bounded slice that can be verified independently.
+5. Add or update deterministic tests near the changed code.
+6. Update durable docs when command behavior, JSON output, safety rules, or
+   recurring workflow guidance changes.
+7. Run the smallest verification ladder that proves the change, then climb if
+   risk increases.
+
+## Bugfix Flow
+
+1. Reproduce or narrow the failure with a test, probe, fixture, saved artifact,
+   or captured browser response.
+2. Locate the smallest owning layer: CLI, command, session, daemon, io, auth,
+   or util.
+3. Fix the root cause with minimal unrelated churn.
+4. Add a regression test or document why one is not practical.
+5. Run a focused test first, then `pnpm agent-verify` when the blast radius
+   warrants it.
+
+## Verification Ladder
+
+1. Focused checks: a single Vitest file, typecheck, or generated-context run.
+2. Deterministic test gate: `pnpm test:unit`.
+3. Agent gate: `pnpm agent-context`, then `pnpm agent-verify`.
+4. Browser/live checks: `pnpm test` or manual/probe-based verification only
+   when the task touches real 1688 browser behavior and the user/session state
+   allows it.
+
+## Human Approval Boundaries
+
+Ask before doing any of these:
+
+- Placing an order or using `checkout confirm --agent`.
+- Logging out or forcing a login reset.
+- Submitting a public GitHub issue with `feedback --submit`.
+- Sending a real seller chat/inquiry unless the user asked for that specific
+  message to be sent.
+- Running live/browser actions that can mutate cart, checkout, seller IM, or
+  account state.
+- Making a breaking JSON contract change.
+
+## Definition Of Done
+
+- The change is implemented in the owning layer.
+- Tests cover the behavior or the reason for no test is recorded.
+- Relevant docs/specs/playbooks/generated indexes are updated.
+- `pnpm agent-verify` passes, or the exact blocker is recorded.

package/docs/exec-plans/README.md

@@ -0,0 +1,9 @@
+# ExecPlans
+
+Use this directory for complex or long-running work that should survive chat
+history loss.
+
+- Active plans: `active/`
+- Completed plans: `completed/`
+- Non-blocking follow-up work: `tech-debt-tracker.md`
+

package/docs/exec-plans/active/README.md

@@ -0,0 +1,4 @@
+# Active ExecPlans
+
+Place in-progress complex work here.
+

package/docs/exec-plans/completed/2026-05-28-sourcing-research-v1.md

@@ -0,0 +1,125 @@
+# Plan: Sourcing Research V1
+
+## Goal
+
+Deliver a complete first version of sourcing research:
+
+- `search` supports research sort/filter flags.
+- `research` runs multi-keyword sourcing research with scoring, dedupe,
+  export, and optional top-N enrichment.
+- `compare` compares offer detail pages by sourcing-relevant fields.
+- Docs, JSON contracts, generated indexes, and tests are updated.
+
+## Context
+
+- Spec: `docs/specs/sourcing-research.md`
+- Backlog: `docs/FEATURES.md`
+- Existing search command: `src/commands/search.ts`
+- Search payload mapping: `src/session/search-mtop.ts`
+- Offer detail command: `src/commands/offer.ts`
+- CLI routing: `src/cli.ts`
+- Output behavior: `src/io/output.ts`
+- Agent rules: `docs/AGENT_WORKING_PRINCIPLES.md`
+
+## Non-Goals
+
+- Do not implement `supplier inspect` until reliable supplier-level payloads
+  are identified.
+- Do not scrape every search result detail page by default.
+- Do not change checkout/cart/seller-message behavior.
+- Do not introduce remote writes.
+
+## Design
+
+1. Extend `search` with:
+   - `--sort`
+   - `--price-min`
+   - `--price-max`
+   - `--province`
+   - `--city`
+   - `--verified`
+   - `--min-turnover`
+   - `--exclude-ads`
+
+   Search remains one fast read-only command. Filtering and deterministic sort
+   happen locally on the collected result set. The search URL may include known
+   remote sort values, but local sorting remains the contract.
+
+2. Add shared sourcing helpers:
+   - normalize sort/filter options
+   - parse turnover/order-count text
+   - score offers and offer details
+   - format JSONL/CSV exports
+
+3. Add `research`:
+   - runs searches sequentially through existing daemon dispatch
+   - dedupes by offerId
+   - computes score/breakdown
+   - optionally enriches top N items through `offer`
+   - emits normal JSON/human output or explicit JSONL/CSV
+
+4. Add `compare`:
+   - validates offer IDs
+   - fetches offer details sequentially
+   - returns item-level errors
+   - scores and sorts comparable summaries
+
+5. Update docs and generated context.
+
+## Self Review
+
+- Risk: `sortType` URL behavior may vary by 1688 page version.
+  - Mitigation: keep local deterministic sorting as the public contract.
+- Risk: supplier scores and repurchase rate may not exist in current payloads.
+  - Mitigation: include nullable fields and do not claim them as available.
+- Risk: enrichment can trigger more browser/detail-page work.
+  - Mitigation: default enrichment to 0; require `--enrich top:N`.
+- Risk: CSV/JSONL could bypass global output flags.
+  - Mitigation: explicit `--jsonl`/`--csv` modes only for `research`, with
+    validation against simultaneous use.
+- Risk: item-level offer failures could abort useful research output.
+  - Mitigation: attach item errors and keep run output when at least one item
+    succeeds.
+
+## Milestones
+
+- [x] Expand spec and plan.
+- [x] Implement search sort/filter helpers and flags.
+- [x] Implement sourcing helper/scoring/export module.
+- [x] Implement `research`.
+- [x] Implement `compare`.
+- [x] Add focused tests.
+- [x] Update docs/backlog.
+- [x] Run `pnpm agent-verify`.
+
+## Verification
+
+```bash
+pnpm test:unit
+pnpm agent-context
+pnpm agent-verify
+```
+
+## Decisions
+
+- 2026-05-28: Keep `supplier inspect` out of V1 because reliable supplier-level
+  payloads are not yet mapped.
+- 2026-05-28: Use local deterministic sorting/filtering as the contract even
+  when adding remote sort URL params.
+- 2026-05-28: Enrichment defaults to off; top-N enrichment is explicit.
+
+## Progress Log
+
+- 2026-05-28: Created spec and plan. Self-review identified remote sort,
+  supplier-score availability, enrichment cost, export-mode validation, and
+  item-level failure handling as the main risks.
+- 2026-05-28: Implemented `search` sort/filter controls, shared sourcing
+  scoring/export helpers, `research`, `compare`, and focused unit tests.
+- 2026-05-28: Verification passed: `pnpm test:unit` (22 files, 151 tests),
+  `pnpm agent-context`, `pnpm agent-verify`, and `pnpm build`.
+
+## Rollback
+
+- Remove `research` and `compare` CLI entries and command files.
+- Revert added `search` flags and helper usage.
+- Regenerate agent context.

package/docs/exec-plans/completed/2026-05-31-supplier-inspect-v1.md

@@ -0,0 +1,113 @@
+# Plan: Supplier Inspect V1
+
+## Goal
+
+Deliver a read-only supplier inspection command backed by real 1688 payloads:
+
+- `1688 supplier inspect <offerId|memberId|offerUrl|factoryCardUrl>`
+- offerId path resolves supplier identity from offer detail and shopcard
+- memberId path resolves factory-card data
+- JSON contract and human output are documented
+- loginId-only input is rejected until a deterministic resolver exists
+
+## Context
+
+- Spec: `docs/specs/supplier-inspect.md`
+- Existing offer detail extraction: `src/commands/offer.ts`
+- CLI routing: `src/cli.ts`
+- Session dispatch: `src/session/dispatch.ts`
+- Response parsing: `src/session/mtop.ts`
+- Recovery behavior: `src/session/recovery.ts`
+- Sourcing helpers/tests: `src/commands/sourcing-utils.ts`,
+  `tests/sourcing-utils.test.ts`
+
+## Non-Goals
+
+- Do not add write actions.
+- Do not bulk crawl a supplier catalog.
+- Do not silently resolve loginId by an unreliable URL.
+- Do not change checkout/cart/seller-message behavior.
+
+## Design
+
+1. Add `src/commands/supplier-inspect.ts`.
+   - Normalize target into offerId or memberId.
+   - Reject loginId-only targets with `BAD_INPUT`.
+   - Use `withRecovery` for page-level failures.
+
+2. OfferId path:
+   - Open `https://detail.1688.com/offer/<offerId>.html`.
+   - Capture `mtop.1688.moga.pc.shopcard`.
+   - Read `sellerModel` from `window.context`.
+   - If a memberId is found, enrich with factory card.
+
+3. MemberId path:
+   - Open `https://sale.1688.com/factory/card.html?memberId=<memberId>`.
+   - Capture `mtop.com.alibaba.china.factory.card.common.fn.mtop.tpp.faas`.
+   - Parse visible factory-card text for available offer count.
+
+4. Output:
+   - Normal human summary lists supplier identity, factory/authentication tags,
+     service scores, location, and offer count.
+   - JSON output follows the spec and remains nullable/additive.
+
+5. Verification:
+   - Add focused unit tests for target normalization and data assembly.
+   - Run `pnpm typecheck`, `pnpm test:unit`, `pnpm agent-context`, and
+     `pnpm agent-map-check`.
+   - Run one live smoke command if session and risk-control state allow.
+
+## Self Review
+
+- Risk: factory card endpoint can time out or not fire.
+  - Mitigation: return partial supplier identity with a warning when offerId
+    data exists but factory-card enrichment fails.
+- Risk: service score key names are not self-explanatory.
+  - Mitigation: keep raw keys and add best-effort labels.
+- Risk: loginId direct lookup may return the wrong supplier.
+  - Mitigation: reject loginId-only input and document the limitation.
+- Risk: available offer count only appears in rendered text.
+  - Mitigation: mark source as `factory-card-dom` and keep nullable.
+
+## Milestones
+
+- [x] Write spec and plan.
+- [x] Implement command, parser, and CLI routing.
+- [x] Add focused tests.
+- [x] Update README, command catalog, JSON contracts, and feature backlog.
+- [x] Regenerate agent context.
+- [x] Run verification.
+
+## Verification
+
+```bash
+pnpm typecheck
+pnpm test:unit
+pnpm agent-context
+pnpm agent-map-check
+pnpm dev supplier inspect 628196518518 --json --pretty
+```
+
+Passed on 2026-05-31:
+
+- `pnpm dev supplier inspect 628196518518 --json --pretty`
+- `pnpm typecheck`
+- `pnpm test:unit`
+- `pnpm docs-check`
+- `pnpm agent-map-check`
+- `pnpm agent-verify`
+
+## Progress Log
+
+- 2026-05-31: Live headed probe identified reliable offer `sellerModel`,
+  shopcard, and factory-card payloads. Direct loginId lookup was rejected after
+  probe showed it can resolve to the wrong factory.
+- 2026-05-31: Implemented `supplier inspect`, CLI routing, dispatch registry,
+  parser helpers, focused tests, docs, generated agent context, and live smoke
+  verification.
+
+## Rollback
+
+- Remove `supplier inspect` CLI entry and command file.
+- Remove tests and docs sections.
+- Regenerate agent context.

package/docs/exec-plans/completed/2026-06-04-supplier-search-v1.md

@@ -0,0 +1,81 @@
+# Supplier Search V1
+
+## Goal
+
+Deliver supplier discovery and research backed by real 1688 company search:
+
+- `1688 supplier search <keyword...>`
+- `1688 supplier research <keyword...>`
+- source must be `companySearchBusinessService`
+- source must not be offer-result supplier aggregation
+- optional top-N enrichment through `supplier inspect`
+
+## Context Read
+
+- Agent principles: `docs/AGENT_WORKING_PRINCIPLES.md`
+- Sourcing spec: `docs/specs/sourcing-research.md`
+- Supplier inspect spec: `docs/specs/supplier-inspect.md`
+- New spec: `docs/specs/supplier-search.md`
+- Existing search/capture patterns: `src/commands/search.ts`,
+  `src/session/search-capture.ts`
+
+## Live Probe Findings
+
+- Company search page:
+  `https://s.1688.com/company/company_search.htm?keywords=<GBK>`
+- `s.1688.com` keywords must be GBK percent-encoded. UTF-8 encoding produced
+  mojibake/zero-result behavior.
+- Business endpoint:
+  `search.1688.com/service/companySearchBusinessService`
+- Payload path:
+  `data.data.companyWithOfferLists`
+- Sample async response returned 14 suppliers with `pageCount=50` and
+  `docsReturn=14`.
+- The async URL used `startIndex=6&asyncCount=14`, so V1 records a known
+  completeness boundary: stable service parsing first, optional SSR/DOM card
+  parsing later if exact first-page completeness is needed.
+
+## Implementation
+
+1. Add shared GBK percent encoder in `src/util/encoding.ts`.
+2. Reuse the encoder in product search URL construction.
+3. Add `src/session/supplier-search.ts`:
+   - request meta reader for `companySearchBusinessService`
+   - service payload parser
+   - supplier/offer-preview mapper
+   - response capture with `keep: "largest"` and settle window
+4. Add `src/commands/supplier-search.ts`:
+   - `supplier search`
+   - `supplier research`
+   - scoring, filters, JSONL/CSV exports
+   - optional enrich through `supplier inspect`
+5. Add CLI and dispatch registry wiring.
+6. Add deterministic unit tests.
+7. Update README, command catalog, JSON contracts, feature backlog, and specs.
+8. Regenerate agent indexes.
+
+## Decisions
+
+- Keep source provenance explicit in JSON:
+  `source.offerAggregation=false`.
+- `supplier search` defaults to `--enrich 0`.
+- `supplier research` defaults to `--enrich top:10`.
+- Rate filters accept both fractions and percentages (`0.4` or `40`).
+- Enrichment requires `memberId`; missing memberId is an item-level error.
+- Do not use direct unauthenticated fetch for company service because it can
+  trigger `x5` interstitials; use browser-emitted responses.
+
+## Verification
+
+- `pnpm typecheck`
+- `pnpm test:unit`
+- `pnpm agent-context`
+- `pnpm agent-verify`
+
+## Rollback
+
+- Remove supplier search/research CLI entries.
+- Remove dispatch registry entry `supplier-search`.
+- Remove `src/commands/supplier-search.ts`.
+- Remove `src/session/supplier-search.ts`.
+- Revert README/docs/spec/test/index updates.

package/docs/exec-plans/completed/2026-06-07-windows-cli-compatibility.md

@@ -0,0 +1,138 @@
+# Plan: Windows CLI Compatibility
+
+## Goal
+
+Deliver the Windows compatibility baseline from
+`docs/specs/windows-cli-compatibility.md`: Windows-safe build/install scripts,
+daemon named pipe isolation, platform-aware diagnostics, Windows-ready docs,
+and deterministic verification.
+
+## Context
+
+- Source spec: `docs/specs/windows-cli-compatibility.md`
+- Agent map: `AGENTS.md`
+- Workflow: `docs/WORKFLOW.md`
+- CLI/package surfaces: `package.json`, `scripts/postinstall.mjs`, `src/cli.ts`
+- Path/daemon surfaces: `src/session/paths.ts`, `src/daemon/*`
+- Diagnostic surface: `src/commands/doctor.ts`
+- User docs: `README.md`, `docs/COMMANDS.md`
+- Generated indexes: `docs/generated/*`
+
+Existing behavior already has partial Windows support: daemon IPC uses a
+named pipe on `win32`, postinstall checks common Windows Chrome paths, and
+most runtime paths use `path.join`. Known gaps are shell `chmod` in
+`package.json`, a fixed global named pipe, Unix-only doctor hints, Unix-only
+README examples, and no deterministic Windows-specific tests.
+
+## Non-goals
+
+- Do not change 1688 login/risk-control behavior.
+- Do not add a native Windows service, installer, or packaged executable.
+- Do not add live Windows 1688 network checks to deterministic tests.
+- Do not change existing command JSON shapes except additive diagnostics if
+  needed.
+
+## Design
+
+- Replace shell `chmod` with a Node script that sets executable mode only on
+  Unix-like platforms.
+- Make Windows named pipe paths stable per root by hashing `root()`.
+- Keep Unix socket paths unchanged.
+- Centralize platform-specific diagnostic hint strings in `doctor`.
+- Make postinstall resolve its pid file through `BB1688_HOME` and run
+  `npx.cmd` on Windows.
+- Use `os.tmpdir()` for production debug/probe output helpers that currently
+  write hard-coded `/tmp` paths.
+- Update README and command docs with PowerShell-safe examples while keeping
+  Unix examples for shell users.
+- Add deterministic tests that simulate Windows behavior without requiring a
+  Windows host by exposing pure helper functions.
+
+## Checklist
+
+Spec and plan foundation:
+
+- [x] Create Windows CLI compatibility spec.
+- [x] Create active ExecPlan.
+
+Implementation:
+
+- [x] Add cross-platform bin-mode script and replace `chmod` build command.
+- [x] Make Windows daemon named pipe unique per `BB1688_HOME` root.
+- [x] Make postinstall daemon pid lookup, npx invocation, and retry hint
+  platform-aware.
+- [x] Make doctor fix hints platform-aware.
+- [x] Replace production hard-coded `/tmp` debug dump paths with `os.tmpdir()`.
+- [x] Add deterministic tests for Windows path/doctor/build helpers.
+
+Docs and maps:
+
+- [x] Update README Windows command-line guidance.
+- [x] Update `docs/COMMANDS.md` Windows examples.
+- [x] Run `pnpm agent-context` after command/doc/test layout changes.
+
+Verification:
+
+- [x] Run focused Windows compatibility tests.
+- [x] Run `pnpm build`.
+- [x] Run `pnpm test:unit`.
+- [x] Run `pnpm agent-verify`.
+- [x] Run `npm pack --dry-run`.
+
+## Verification
+
+Focused:
+
+```bash
+pnpm exec vitest run tests/paths.test.ts tests/doctor.test.ts tests/fix-bin-mode.test.ts
+```
+
+Package and project:
+
+```bash
+pnpm build
+pnpm test:unit
+pnpm agent-context
+pnpm agent-verify
+npm pack --dry-run
+```
+
+Manual Windows smoke when a Windows machine is available:
+
+```powershell
+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
+```
+
+## Decisions
+
+- 2026-06-07: Treat Windows support as a deterministic packaging/runtime
+  compatibility baseline, not a guarantee that live 1688 network calls pass in
+  CI without a logged-in account.
+- 2026-06-07: Use `BB1688_HOME` root hashing for Windows named pipes so
+  tests and users with different homes do not collide.
+
+## Progress Log
+
+- 2026-06-07: Created spec and active plan from user request.
+- 2026-06-07: Implemented the Windows compatibility baseline: Node-based bin
+  mode fixing, root-hashed Windows daemon named pipes, platform-aware
+  postinstall and doctor hints, `os.tmpdir()` debug paths, PowerShell docs, and
+  deterministic helper tests.
+- 2026-06-07: Verified with focused Windows compatibility tests, `pnpm build`,
+  `pnpm test:unit`, `pnpm agent-context`, `pnpm agent-verify`, and
+  `npm pack --dry-run`. Manual Windows smoke remains documented for a real
+  Windows session.
+
+## Rollback
+
+- Restore `package.json` build script to its previous `chmod` form.
+- Restore `socketPath()` to the fixed Windows pipe.
+- Revert postinstall, doctor, docs, and tests added by this plan.
+- Run `pnpm agent-context` after rollback if generated indexes changed.