1688-cli 0.1.41 → 0.1.43

package/docs/JSON_CONTRACTS.md

@@ -0,0 +1,476 @@
+# JSON Contracts
+
+The CLI auto-switches to JSON when stdout is piped. Stable JSON output is part
+of the agent contract. Prefer additive changes; do not rename or remove fields
+without an explicit breaking-change decision.
+
+## Output Rules
+
+- `--json` forces JSON in a TTY.
+- `--pretty` indents JSON by two spaces.
+- `--get <path>` prints one dot-path. Scalars are raw lines; objects and arrays
+  remain JSON.
+- `--pick <paths>` emits a JSON object with each requested path as a key.
+- Watch commands emit line-delimited JSON, one object per new event/message.
+
+## `whoami`
+
+```ts
+{ loggedIn: true, memberId: string, nick: string, lastVerifiedAt: string }
+{ loggedIn: false }
+```
+
+## `daemon status`
+
+`daemon status` is profile-scoped. When `--profile` is omitted, `profile` is
+`default`.
+
+```ts
+{
+  profile: string,
+  running: boolean,
+  pid?: number,
+  reachable?: boolean,
+  version?: string | null,
+  expectedVersion?: string,
+  versionMatches?: boolean,
+  stats?: {
+    profile: string,
+    version: string,
+    startedAt: string,
+    pid: number,
+    commandCount: number,
+    lastRequestAt: string | null,
+    lastError: string | null,
+    uptimeMs: number,
+    activeClients: number,
+    browser: {
+      profile: string | null,
+      browserAlive: boolean,
+      pageCount: number,
+      currentUrl: string | null,
+      pageState: object | null,
+      loggedIn: boolean | null,
+    },
+    health: object,
+  },
+}
+```
+
+## `profile status`
+
+```ts
+{
+  profile: {
+    name: string,
+    path: string,
+    exists: boolean,
+    locked: boolean,
+    loggedIn: boolean,
+    recentRequestId: string | null,
+    recentStatus: string | null,
+    recentErrorCode: string | null,
+    daemon: {
+      profile: string,
+      running: boolean,
+      pid?: number,
+      reachable?: boolean,
+      version?: string | null,
+      expectedVersion?: string,
+      versionMatches?: boolean,
+    },
+  },
+  state: {
+    version: 1,
+    memberId?: string,
+    nick?: string,
+    loggedInAt?: string,
+    lastVerifiedAt?: string,
+  } | null,
+}
+```
+
+## `doctor`
+
+`doctor --profile <name>` checks that profile's directory, lock, state,
+daemon, and live daemon socket. JSON output includes the selected `profile` and
+the matching profile-scoped daemon status.
+
+```ts
+{
+  ok: boolean,
+  profile: string,
+  checks: Array<{ name: string, status: "ok" | "warn" | "fail", message: string, fix?: string }>,
+  version: VersionInfo,
+  daemon: DaemonStatus | null,
+}
+```
+
+## `search`, `similar`, `image-search`
+
+```ts
+{
+  keyword?: string,
+  imageId?: string,
+  offerId?: string,
+  sort?: "relevance" | "best-selling" | "price-asc" | "price-desc",
+  filters?: object,
+  totalBeforeFilter?: number,
+  total: number,
+  offers: Array<{
+    offerId: string,
+    title: string,
+    price: { text: string, min: number | null, max: number | null },
+    supplier: { name: string | null, shopUrl: string | null, years: number | null },
+    location: { province: string | null, city: string | null },
+    bizType: string | null,
+    verified: { factory: boolean, business: boolean, superFactory: boolean },
+    tags: string[],
+    serviceTags?: string[],
+    productBadges?: string[],
+    demand?: {
+      orderCountText: string | null,
+      orderCount: number | null,
+      repurchaseRateText: string | null,
+      repurchaseRate: number | null,
+    },
+    isP4P: boolean,
+    turnover: string | null,
+    url: string,
+    image: string | null,
+  }>
+}
+```
+
+## `research`
+
+Normal JSON result:
+
+```ts
+{
+  queries: string[],
+  sort: "relevance" | "best-selling" | "price-asc" | "price-desc",
+  filters: object,
+  maxPerQuery: number,
+  enrichTop: number,
+  total: number,
+  enrichedCount: number,
+  items: Array<{
+    sourceKeyword: string,
+    sourceRank: number,
+    globalRank: number,
+    offer: Offer,
+    demand: {
+      turnoverText: string | null,
+      orderCount: number | null,
+      repurchaseRate: number | null,
+    },
+    supplier: {
+      years: number | null,
+      verified: Offer["verified"],
+      tags: string[],
+      isAd: boolean,
+    },
+    score: number,
+    scoreBreakdown: Array<{ name: string, points: number, reason: string }>,
+    enriched?: OfferDetailSummary,
+    error?: { code: string, message: string },
+  }>,
+}
+```
+
+`--jsonl` emits one research item per line. `--csv` emits a CSV table.
+
+## `compare`
+
+```ts
+{
+  total: number,
+  ok: number,
+  failed: number,
+  items: Array<{
+    offerId: string,
+    ok: boolean,
+    score: number | null,
+    scoreBreakdown: Array<{ name: string, points: number, reason: string }>,
+    summary: OfferDetailSummary | null,
+    error?: { code: string, message: string },
+  }>,
+}
+```
+
+## `supplier inspect`
+
+```ts
+{
+  target: {
+    input: string,
+    type: "offerId" | "memberId",
+    offerId: string | null,
+    memberId: string | null,
+  },
+  supplier: {
+    name: string | null,
+    loginId: string | null,
+    memberId: string | null,
+    userId: string | null,
+    companyId: string | null,
+    shopUrl: string | null,
+    shopUrls: Record<string, string>,
+    identity: string | null,
+    signs: Record<string, boolean>,
+  },
+  factory: {
+    isFactory: boolean,
+    superFactory: boolean,
+    tpYears: number | null,
+    medalLevel: string | null,
+    thirdPartyAuthProvider: string | null,
+    establishedAtText: string | null,
+    location: string | null,
+    address: string | null,
+    coordinates: { latitude: number | null, longitude: number | null },
+    productionService: string | null,
+    employeeScale: string | null,
+    workerCount: string | null,
+    profile: string | null,
+    tags: string[],
+  },
+  trust: {
+    companyLabel: string | null,
+    retentionRate: number | null,
+    companyIcons: Array<{ title: string, link: string | null }>,
+    shopTags: string[],
+    serviceScores: Array<{ key: string, label: string, score: number | null }>,
+  },
+  offers: { availableCount: number | null, source: "factory-card-dom" | null },
+  sources: {
+    offerUrl: string | null,
+    factoryCardUrl: string | null,
+    shopcardCaptured: boolean,
+    factoryCardCaptured: boolean,
+  },
+  warnings: string[],
+}
+```
+
+V1 supports offerId, offer URL, `b2b-*` memberId, and factory-card URL.
+loginId-only input is rejected because live probing showed it can resolve to
+the wrong supplier.
+
+## `supplier search`, `supplier research`
+
+Supplier discovery uses 1688 company search
+(`companySearchBusinessService`). It must not be treated as offer-search
+supplier aggregation.
+
+```ts
+{
+  queries: string[],
+  source: {
+    kind: "company-search",
+    endpoint: "companySearchBusinessService",
+    offerAggregation: false,
+  },
+  filters: {
+    factoryOnly: boolean,
+    province: string | null,
+    city: string | null,
+    minYears: number | null,
+    minRepeatRate: number | null,
+    minResponseRate: number | null,
+  },
+  maxPerQuery: number,
+  enrichTop: number,
+  totalBeforeFilter: number,
+  total: number,
+  enrichedCount: number,
+  items: Array<{
+    sourceKeyword: string,
+    sourceRank: number,
+    globalRank: number,
+    supplier: {
+      companyName: string,
+      loginId: string | null,
+      memberId: string | null,
+      enterpriseId: string | null,
+      realUserId: string | null,
+      companyId: string | null,
+      shopUrl: string | null,
+      factoryCardUrl: string | null,
+      domainUri: string | null,
+      location: {
+        province: string | null,
+        city: string | null,
+        address: string | null,
+        latitude: number | null,
+        longitude: number | null,
+      },
+      productionService: string | null,
+      businessMode: string | null,
+      tp: {
+        memberLevel: string | null,
+        serviceYears: number | null,
+        tpNum: number | null,
+      },
+      factory: {
+        isFactory: boolean,
+        factoryTag: string | null,
+        factoryLevel: string | null,
+        shiliFactory: boolean,
+        shiliCompany: boolean,
+        superFactory: boolean,
+        businessInspection: boolean,
+        factoryInspection: boolean,
+        qiJianCompany: boolean,
+        safePurchase: boolean,
+        trust: boolean,
+      },
+      service: {
+        compositeScore: number | null,
+        wwResponseRate: number | null,
+        repeatRate: number | null,
+        complianceRate: number | null,
+      },
+      demand: {
+        payOrderCount3m: number | null,
+        payAmount3m: number | null,
+        fuzzyPayAmount3m: string | null,
+        saleQuantity3m: number | null,
+        memberBookedCount: number | null,
+      },
+      tags: string[],
+      offersPreview: Array<{
+        offerId: string | null,
+        title: string,
+        url: string | null,
+        price: { text: string | null, value: number | null },
+        unit: string | null,
+        image: string | null,
+        bookedCount: number | null,
+        saleQuantity: number | null,
+        quantitySumMonth: number | null,
+        brief: string | null,
+      }>,
+    },
+    score: number,
+    scoreBreakdown: Array<{ name: string, points: number, reason: string }>,
+    inspect?: SupplierInspectResult,
+    error?: { code: string, message: string },
+  }>,
+}
+```
+
+`supplier search` defaults to `--enrich 0`; `supplier research` defaults to
+`--enrich top:10`. `--jsonl` emits one supplier item per line. `--csv` emits a
+CSV table.
+
+## `offer`
+
+```ts
+{
+  offerId: string,
+  title: string,
+  url: string,
+  priceRange: string | null,
+  priceMin: number | null,
+  priceMax: number | null,
+  unitName: string | null,
+  minOrderQty: number | null,
+  mixOrderQty: number | null,
+  priceTiers: Array<{ minQty: number, price: number }>,
+  detailUrl: string | null,
+  attributes: Array<{ name: string, value: string }>,
+  packageInfo: Array<{
+    skuId: string,
+    spec: string,
+    length: number | null,
+    width: number | null,
+    height: number | null,
+    weight: number | null,
+    volume: number | null,
+  }>,
+  supplier: {
+    name: string | null,
+    loginId: string | null,
+    memberId: string | null,
+    userId: string | null,
+  },
+  freight: {
+    receiveAddress: string | null,
+    sendArea: string | null,
+    province: string | null,
+    city: string | null,
+    unitWeight: number | null,
+  },
+  saledCount: number | null,
+  categoryId: string | null,
+  options: Array<{ prop: string, values: Array<{ name: string, imageUrl: string | null }> }>,
+  skus: Array<{
+    skuId: string,
+    specs: string,
+    price: number | null,
+    multiPrice: number | null,
+    stock: number | null,
+    saleCount: number,
+    image: string | null,
+  }>,
+  mainImage: string | null,
+  images: string[],
+}
+```
+
+## `seller messages`
+
+One-shot result:
+
+```ts
+{
+  conversation: string,
+  total: number,
+  messages: Array<{
+    sender: string,
+    time: string | null,
+    isMine: boolean,
+    content: string,
+    read: boolean,
+    kind: "text" | "offerCard" | "orderCard" | "autoReply"
+        | "assessment" | "image" | "other",
+    card?: {
+      title: string | null,
+      price: string | null,
+      image: string | null,
+      url: string | null,
+    },
+    messageId?: string,
+  }>,
+}
+```
+
+Watch mode emits one object per new message:
+
+```ts
+{ conversation: string, message: Message }
+```
+
+## `cart add`
+
+```ts
+{
+  ok: boolean,
+  added: CartItem,
+  isNewRow: boolean,
+  addedQuantity: number,
+}
+```
+
+## `order list`
+
+Orders include buyer actions, service entries, and display badges. Preserve
+`actions[]`, `services[]`, and `badges[]` because downstream agents use them to
+decide what follow-up is possible.
+
+## Generated Shape Index
+
+Run `pnpm agent-context` to refresh `docs/generated/json-shapes.md`, which
+indexes exported TypeScript interfaces from command modules.

package/docs/QUALITY_SCORE.md

@@ -0,0 +1,61 @@
+# Quality Score
+
+This file tracks agent-readiness and known quality gaps. Keep it blunt and
+mechanical; it is a map for improvement, not a blame document.
+
+## Current Score
+
+Overall: 6 / 10
+
+## Strengths
+
+- Clear buyer-journey command surface exists: sourcing, inquiry, cart,
+  checkout, tracking, and post-sale chat.
+- Commands expose JSON automatically when piped and support `--json`,
+  `--pretty`, `--get`, and `--pick`.
+- Real browser/session behavior is centralized under `src/session`.
+- Profile-scoped daemons give agents warm browser contexts without forcing
+  unrelated profiles through one global lock.
+- Checkout and feedback write actions already have explicit safety protocols.
+- Deterministic Vitest coverage exists for output, mtop parsing, recovery,
+  page-state, inbox cards, and fixtures through `pnpm test:unit`.
+- Agent map docs and generated indexes now exist.
+
+## Gaps Blocking Higher Agent Autonomy
+
+- `AGENTS.md` was historically long; future work should keep it short and keep
+  durable detail in `docs/`.
+- Generated context is heuristic and should improve as command/result types
+  evolve.
+- Browser/live verification is not part of the default gate and needs explicit
+  manual/probe checks.
+- Sourcing research fields such as repurchase rate, supplier scores, and
+  service badges are not yet normalized.
+- Some probe scripts are exploratory and not documented as stable workflows.
+- JSON compatibility policy exists in docs but is not yet enforced by schema
+  tests.
+
+## Last Known Verification Snapshot
+
+On 2026-05-28, `pnpm agent-verify` passed:
+
+- `pnpm typecheck`
+- `pnpm test:unit` (22 files, 151 tests)
+- `pnpm docs-check`
+- `pnpm agent-map-check`
+
+On 2026-05-28, full `pnpm test` failed in `tests/doctor-live.test.ts` because
+the live doctor checks returned `DOCTOR_FAILED` in the current local
+environment. The default agent gate uses `pnpm test:unit` to keep live checks
+explicit.
+
+## Quality Targets
+
+- 6 / 10: short map, docs map, generated indexes, and default verification
+  gate exist.
+- 7 / 10: JSON contract tests cover all stable command outputs and docs-check
+  runs in CI.
+- 8 / 10: browser/live verification playbooks are repeatable and key mtop
+  payloads have fixture-backed parsers.
+- 9 / 10: sourcing research scoring, supplier-quality extraction, and
+  autonomous inbox workflows have deterministic harness tests.

package/docs/README.md

@@ -0,0 +1,36 @@
+# Documentation Map
+
+This directory is the canonical knowledge base for agents and humans working on
+`1688-cli`. Keep `AGENTS.md` short and put durable context here.
+
+## Start Here
+
+- Agent working principles: [`AGENT_WORKING_PRINCIPLES.md`](AGENT_WORKING_PRINCIPLES.md)
+- Repository architecture: [`../ARCHITECTURE.md`](../ARCHITECTURE.md)
+- Default workflow: [`WORKFLOW.md`](WORKFLOW.md)
+- Command catalog: [`COMMANDS.md`](COMMANDS.md)
+- JSON contracts: [`JSON_CONTRACTS.md`](JSON_CONTRACTS.md)
+- Safety rules: [`SAFETY.md`](SAFETY.md)
+- Reliability notes: [`RELIABILITY.md`](RELIABILITY.md)
+- Quality score: [`QUALITY_SCORE.md`](QUALITY_SCORE.md)
+- Feature backlog: [`FEATURES.md`](FEATURES.md)
+- Agent maps plan: [`AGENT_MAPS_PLAN.md`](AGENT_MAPS_PLAN.md)
+
+## Domain Knowledge
+
+- Specs: [`specs/`](specs/)
+- Repeatable playbooks: [`playbooks/`](playbooks/)
+- Records and postmortems: [`records/`](records/)
+- Generated repository indexes: [`generated/`](generated/)
+- Long-running plans: [`exec-plans/`](exec-plans/)
+
+## Maintenance Rules
+
+- Update command docs when command names, flags, behavior, or examples change.
+- Update JSON contracts when agent-facing output shape changes.
+- Update safety docs when a write action, approval boundary, login flow, or
+  checkout behavior changes.
+- Add or update a playbook when an agent repeats the same workflow twice.
+- Run `pnpm agent-context` after changing commands, exported result
+  interfaces, source layout, or tests.
+- Run `pnpm agent-verify` before handoff, or record the exact blocker.

package/docs/RELIABILITY.md

@@ -0,0 +1,69 @@
+# Reliability
+
+`1688-cli` depends on a live website, browser automation, mtop responses, and a
+real logged-in buyer session. Reliability work should make failures explicit
+and recoverable for agents.
+
+## Daemon
+
+Each daemon routes commands for one profile through one persistent Chromium
+context. Different profiles use different daemon processes, locks, sockets or
+named pipes, pid/version/log files, state files, and persistent browser
+directories.
+
+Benefits:
+
+- Saves Chrome cold-start time.
+- Keeps one continuous logged-in session per profile.
+- Adds inter-command jitter.
+- Allows different profiles to run at the same time without sharing one
+  process lock.
+
+Use `1688 daemon start` near the beginning of a session with multiple 1688
+commands. Use `1688 daemon start --profile <name>` for a non-default profile.
+The daemon auto-stops after inactivity. Run `1688 daemon reload --profile
+<name>` after package updates or after manually resolving profile-specific
+browser issues.
+
+`login`, `logout`, and `doctor` stay inline because they need interactive UI,
+browser windows, or environment checks. `login --profile <name>` can
+auto-start that profile daemon after the login state is available.
+
+## Watch Mode
+
+`1688 seller messages ... --watch` is designed to stay alive.
+
+- It prints a baseline line to stderr.
+- It emits one JSON object to stdout for each newly-arrived message.
+- History is not re-emitted.
+- Deduplication uses server-side `messageId` when present.
+- It exits cleanly on SIGINT.
+
+Agent loops should parse stdout line by line and should not assume the process
+will exit by itself.
+
+## Browser Recovery
+
+Commands should detect and report:
+
+- login redirects
+- risk-control / slider pages
+- closed browser windows
+- empty mtop captures
+- network failures
+
+Use structured `CliError` exit codes so agents can choose the next safe step.
+
+## Probes And Fixtures
+
+Probe scripts under `scripts/probe-*.mjs` are useful for discovering page
+behavior, selectors, and mtop payloads. They are not stable automated tests.
+
+Stable behavior belongs in `tests/` with fixtures where possible.
+
+## Live-Service Boundaries
+
+`pnpm test:unit` is the deterministic default. `pnpm test` also runs live
+doctor checks and may depend on local browser/session state. Browser or
+account-mutating checks should be explicit, bounded, and documented in the
+final response when they cannot be run.