@wport/cli 0.8.0 → 0.9.1-dev.0

package/CHANGELOG.md

@@ -5,6 +5,21 @@
 
 ---
 
+## [0.9.0] — 2026-08-10
+
+### Added
+
+- **個人線(pm_47)· `wport personal apply` 投遞**(對接 talent `/api/v1/personal/applications`):
+  - 單筆:`personal apply <job_enc_id> --resume <enc_id> --message <text> | --message-file <path|-> --confirm`
+    ——message 互斥二擇一必填、trim 後 1~2000 字**本地先驗**(超長/空 exit 2 不發請求)、`-` 讀 stdin;
+    投遞對雇主可見,無 `--confirm` 一律 exit 2 不發請求;自動附 `Idempotency-Key`。
+  - 批次:`personal apply --file <batch.json> --confirm`——`{"applications":[…]}` ≤20 筆與逐筆 message
+    本地先驗(超限 exit 2);輸出 succeeded/failed 表,`--output json` 給完整陣列。
+  - **錯誤分流**:冷卻 409(印 `next_apply_at`)、職缺終態 409、日上限 429(印剩餘額度 / `resets_at`)
+    → 統一 exit 3 + 人類可讀;其餘 4xx 沿既有 exit code 契約。
+- codegen:凍結 `docs/handoff/swagger-wport-personal-api-v1.{json,yaml}` 納入 applications 端點,
+  `PERSONAL_APPLICATIONS_BASE` 常數;`gen:openapi:personal` 經 `--keep-prefix` 自動含 applications。
+
 ## [0.8.0] — 2026-07-30
 
 ### Added

package/README.md

@@ -16,6 +16,16 @@ npm install -g @wport/cli
 
 Requires Node.js >= 18.17.
 
+### dev channel(內部測試用)
+
+`@wport/cli@dev` 是預設連 dev 後端(`https://developers.wport.me/v2`)的建置,供內部測試未上 prod 的後端改動:
+
+    npm i -g @wport/cli@dev     # wport → dev 後端
+    wport login                 # 直接對 dev 後端做 device flow
+    npm i -g @wport/cli@latest  # 換回 prod 版
+
+dev 版憑證獨立存於 `credentials-dev.json`,與 prod 版的 `credentials.json` 互不干擾;`wport doctor` 會印出目前 channel。base URL 仍可用 `--api` / `WPORT_API_BASE` 覆寫。
+
 ## Quick start
 
 ```bash
@@ -139,6 +149,11 @@ wport personal resumes publish <enc_id>              # searchable by companies (
 wport personal resumes delete <enc_id> --confirm
 wport personal resumes export --out ./backup
 
+# Apply to jobs (visible to the employer; requires --confirm; 20/day)
+wport personal apply <job_enc_id> --resume <enc_id> --message "自我介紹…" --confirm
+wport personal apply <job_enc_id> --resume <enc_id> --message-file intro.txt --confirm   # or - for stdin
+wport personal apply --file batch.json --confirm     # { "applications": [...] }, max 20, partial success
+
 # Sign out (revokes the refresh token server-side, clears local credentials)
 wport logout
 ```
@@ -309,6 +324,19 @@ Three codegen variants — pick whichever matches your setup:
 
 The `:prod` / `:remote` variants go through `scripts/gen-from-remote.cjs`, which filters the upstream spec down to the endpoints this CLI uses (it ignores unrelated `$ref` breakage elsewhere in the spec). When the CLI starts using a new endpoint, add it to `KEEP_PATHS` in that script.
 
+#### 發 dev channel 到 npm
+
+    npm version prerelease --preid=dev --no-git-tag-version   # 0.9.0 → 0.9.1-dev.0(prerelease 會先進 patch)
+    npm run build:dev                                         # 選用:發布前先在本地確認 dev build 行為正常
+    # 發布必須帶 WPORT_BUILD_CHANNEL=dev:否則 npm publish 的 prepublishOnly hook 會跑 `npm run build`(prod),
+    # 把 dist 覆寫回 prod 產物,結果 @wport/cli@dev 底下發成 prod build(靜默、不報錯)。
+    WPORT_BUILD_CHANNEL=dev npm publish --tag dev --otp <code> # 必須顯式帶 --tag dev
+    npm view @wport/cli dist-tags                             # 斷言 latest 未被動到
+
+⚠️ npm 預設 tag 是 `latest`,即使版號是 prerelease;漏掉 `--tag dev` 會把 `latest` 指到 dev 版,污染所有 `npm i @wport/cli`。發布後務必用 `npm view dist-tags` 確認 `latest` 沒變。
+
+⚠️ `package.json` 的 `prepublishOnly` 會在 `npm publish` 時自動重跑 `npm run build`(prod build,無 dev channel),覆寫掉上一步 `build:dev` 產出的 dist。真正決定 channel 的是 publish 指令本身的 `WPORT_BUILD_CHANNEL=dev` 前綴 —— 該 env 會被 npm 傳進 prepublishOnly 的子行程,讓重跑的 `npm run build` 也讀到 dev channel。漏掉這個前綴,`@wport/cli@dev` 就會靜默發成連 `api.wport.me` 的 prod build。
+
 ## Support
 
 This CLI is in pre-release. Bug reports and feature requests are best-effort and handled directly by the maintainer.

package/dist/index.js

@@ -179,7 +179,7 @@ function isTimeoutAbort(err) {
   return false;
 }
 function buildUserAgent() {
-  return `wport-cli/${"0.8.0"} (node ${process.version}; ${process.platform})`;
+  return `wport-cli/${"0.9.1-dev.0"} (node ${process.version}; ${process.platform})`;
 }
 function unwrapDataResponse(body) {
   if (body && typeof body === "object" && "success" in body && "data" in body) {
@@ -366,8 +366,26 @@ function validateAndCoerce(key, value) {
   }
 }
 
+// src/lib/channel.ts
+var CHANNEL_BASE_URL = {
+  prod: "https://api.wport.me",
+  dev: "https://developers.wport.me/v2"
+};
+function currentChannel() {
+  return true ? "dev" : "prod";
+}
+function channelBaseUrl(channel) {
+  return CHANNEL_BASE_URL[channel] ?? CHANNEL_BASE_URL.prod;
+}
+function channelBanner() {
+  const channel = currentChannel();
+  if (channel === "prod") return null;
+  return `[${channel}] targeting the dev backend
+`;
+}
+
 // src/lib/global-opts.ts
-var DEFAULT_BASE_URL = "https://api.wport.me";
+var DEFAULT_BASE_URL = channelBaseUrl(currentChannel());
 var API_BASE_ENV_VAR = "WPORT_API_BASE";
 var DEFAULT_LOCALE = "zh-TW";
 var DEFAULT_TIMEOUT_MS = 1e4;
@@ -981,7 +999,8 @@ var KEY_PREFIX = "wpk_live_";
 var KEY_MIN_LENGTH = KEY_PREFIX.length + 32;
 var paths2 = (0, import_env_paths2.default)("wport", { suffix: "" });
 function getCredentialsPath() {
-  return (0, import_node_path2.join)(paths2.config, "credentials.json");
+  const fileName = currentChannel() === "dev" ? "credentials-dev.json" : "credentials.json";
+  return (0, import_node_path2.join)(paths2.config, fileName);
 }
 function isValidKeyFormat(key) {
   return key.startsWith(KEY_PREFIX) && key.length >= KEY_MIN_LENGTH && !/\s/.test(key);
@@ -1148,6 +1167,7 @@ function ensureFormat(key, source) {
 
 // src/lib/personal-types.ts
 var PERSONAL_RESUMES_BASE = "/api/v1/personal/resumes";
+var PERSONAL_APPLICATIONS_BASE = "/api/v1/personal/applications";
 var OAUTH_BASE = "/api/oauth";
 var OAUTH_SESSIONS_BASE = `${OAUTH_BASE}/sessions`;
 var SECTION_WRITE_PLAN = {
@@ -1252,11 +1272,12 @@ function registerDoctorCommand(program2) {
 }
 async function runDoctor(ctx) {
   const line = (s = "") => process.stdout.write(s + "\n");
-  line(`wport-cli ${"0.8.0"}`);
+  line(`wport-cli ${"0.9.1-dev.0"}`);
   line(`  bundled schema fingerprint: ${"839e8a891dfb"}`);
   line("");
   line("Resolved configuration:");
   line(`  API base URL: ${ctx.baseUrl}`);
+  line(`  channel:      ${currentChannel()}`);
   line(`  locale:       ${ctx.locale}`);
   line(`  timeout:      ${ctx.timeoutMs}ms`);
   const cfgPath = getConfigPath();
@@ -1426,6 +1447,8 @@ function warnIfRateLimitLow(headers) {
 
 // src/commands/enterprise/login.ts
 async function performLogin(ctx, key) {
+  const banner = channelBanner();
+  if (banner) process.stderr.write(banner);
   if (!isValidKeyFormat(key)) {
     throw new CliError(
       `That does not look like a valid ${KEY_PREFIX} key. Nothing was saved.`,
@@ -2743,6 +2766,8 @@ function describeIdentity(displayName, email) {
   return "this device";
 }
 async function performLogin2(ctx, flags, deps = {}) {
+  const banner = channelBanner();
+  if (banner) process.stderr.write(banner);
   const openBrowser = deps.openBrowser ?? openInBrowser;
   const hostnameFn = deps.hostname ?? import_node_os.hostname;
   if (!flags.force) {
@@ -4542,15 +4567,170 @@ function registerPersonalResumesCommand(parent) {
   registerPersonalResumesDelete(resumes);
 }
 
+// src/commands/personal/apply/index.ts
+var import_node_crypto15 = require("crypto");
+var import_node_fs11 = require("fs");
+
+// src/commands/personal/apply/message-input.ts
+var import_node_fs10 = require("fs");
+var MAX_MESSAGE = 2e3;
+function defaultReadStdin() {
+  return (0, import_node_fs10.readFileSync)(0, "utf8");
+}
+function validateMessageText(raw) {
+  const trimmed = raw.trim();
+  if (trimmed.length < 1) {
+    throw new CliError("application message must not be empty (1~2000 chars) \u61C9\u5FB5\u8A0A\u606F\u5FC5\u586B", ExitCode.InvalidArgument);
+  }
+  if (trimmed.length > MAX_MESSAGE) {
+    throw new CliError(`application message exceeds ${MAX_MESSAGE} chars \u61C9\u5FB5\u8A0A\u606F\u4E0D\u53EF\u8D85\u904E 2000 \u5B57`, ExitCode.InvalidArgument);
+  }
+  return trimmed;
+}
+function resolveMessage(opts) {
+  const hasMsg = opts.message !== void 0;
+  const hasFile = opts.messageFile !== void 0;
+  if (hasMsg && hasFile) {
+    throw new CliError("--message and --message-file are mutually exclusive \u4E92\u65A5", ExitCode.InvalidArgument);
+  }
+  if (!hasMsg && !hasFile) {
+    throw new CliError("--message or --message-file is required \u61C9\u5FB5\u8A0A\u606F\u5FC5\u586B", ExitCode.InvalidArgument);
+  }
+  if (hasMsg) return validateMessageText(opts.message);
+  const file = opts.messageFile;
+  const raw = file === "-" ? (opts.readStdin ?? defaultReadStdin)() : (0, import_node_fs10.readFileSync)(file, "utf8");
+  return validateMessageText(raw);
+}
+function validateBatchItems(items) {
+  if (!Array.isArray(items) || items.length < 1) {
+    throw new CliError('batch file must contain a non-empty "applications" array', ExitCode.InvalidArgument);
+  }
+  if (items.length > 20) {
+    throw new CliError(`batch exceeds 20 items (got ${items.length}) \u6279\u6B21\u4E0A\u9650 20 \u7B46`, ExitCode.InvalidArgument);
+  }
+  return items.map((it, i) => {
+    const o = it;
+    const jobId = typeof o?.enc_job_id === "string" ? o.enc_job_id.trim() : "";
+    const resumeId = typeof o?.enc_resume_id === "string" ? o.enc_resume_id.trim() : "";
+    if (!jobId || !resumeId) {
+      throw new CliError(`batch item #${i}: enc_job_id and enc_resume_id required`, ExitCode.InvalidArgument);
+    }
+    const message = validateMessageText(typeof o?.application_message === "string" ? o.application_message : "");
+    return { enc_job_id: jobId, enc_resume_id: resumeId, application_message: message };
+  });
+}
+
+// src/commands/personal/apply/index.ts
+function rethrowApplyError(err) {
+  if (err instanceof ServerClientHttpError) {
+    const body = err.body ?? null;
+    const code = body?.error_code;
+    if (err.status === 409 && code === "application_cooldown") {
+      throw new CliError(`Application in cooldown. Next apply at: ${body?.next_apply_at ?? "unknown"}`, ExitCode.ServerClientError);
+    }
+    if (err.status === 409 && code === "job_not_available") {
+      throw new CliError("Job is no longer available (closed or removed).", ExitCode.ServerClientError);
+    }
+    if (err.status === 429 && code === "apply_daily_limit_reached") {
+      throw new CliError(
+        `Daily application limit reached (${body?.used}/${body?.limit}). Resets at: ${body?.resets_at ?? "tomorrow"}`,
+        ExitCode.ServerClientError
+      );
+    }
+  }
+  throw err;
+}
+async function runPersonalApply(ctx, args) {
+  if (!args.confirm) {
+    throw new CliError(
+      "Refusing to apply without --confirm (application is visible to the employer)",
+      ExitCode.InvalidArgument
+    );
+  }
+  const opts = { baseUrl: ctx.baseUrl, locale: ctx.locale, timeoutMs: ctx.timeoutMs };
+  const body = { enc_job_id: args.encJobId, enc_resume_id: args.encResumeId, application_message: args.message };
+  let result;
+  try {
+    result = await personalPost(opts, PERSONAL_APPLICATIONS_BASE, body, { idempotencyKey: (0, import_node_crypto15.randomUUID)() });
+  } catch (err) {
+    rethrowApplyError(err);
+  }
+  const data = result.body?.data ?? {};
+  if (ctx.format === "json") {
+    printJson(data);
+    return;
+  }
+  process.stdout.write(`Applied. application: ${sanitizeForTerminal(String(data.enc_application_id ?? ""))}
+`);
+  const q = data.quota;
+  if (q) process.stdout.write(`Daily quota: ${q.used}/${q.limit} used, ${q.remaining} remaining
+`);
+}
+function registerPersonalApplyCommand(parent) {
+  parent.command("apply [job_enc_id]").description("Apply to a job (single) or batch via --file (requires --confirm)").option("--resume <enc_id>", "resume enc_id to apply with (single mode)").option("--message <text>", "application message (1~2000 chars)").option("--message-file <path>", "read application message from file (use - for stdin)").option("--file <path>", 'batch JSON file { "applications": [...] } (max 20)').option("--confirm", "confirm this outward-facing action").action(async (jobEncId, flags, command) => {
+    const ctx = resolveContext(command);
+    if (flags.file) {
+      await runPersonalApplyBatch(ctx, { file: flags.file, confirm: flags.confirm === true });
+      return;
+    }
+    if (!jobEncId || !flags.resume) {
+      throw new CliError("single apply requires <job_enc_id> and --resume", ExitCode.InvalidArgument);
+    }
+    const message = resolveMessage({ message: flags.message, messageFile: flags.messageFile });
+    await runPersonalApply(ctx, {
+      encJobId: jobEncId,
+      encResumeId: flags.resume,
+      message,
+      confirm: flags.confirm === true
+    });
+  });
+}
+async function runPersonalApplyBatch(ctx, args) {
+  if (!args.confirm) {
+    throw new CliError(
+      "Refusing to apply without --confirm (applications are visible to employers)",
+      ExitCode.InvalidArgument
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse((0, import_node_fs11.readFileSync)(args.file, "utf8"));
+  } catch {
+    throw new CliError(`Cannot read/parse batch file: ${args.file}`, ExitCode.InvalidArgument);
+  }
+  const items = validateBatchItems(parsed?.applications);
+  const opts = { baseUrl: ctx.baseUrl, locale: ctx.locale, timeoutMs: ctx.timeoutMs };
+  let result;
+  try {
+    result = await personalPost(opts, `${PERSONAL_APPLICATIONS_BASE}/batch`, { applications: items }, { idempotencyKey: (0, import_node_crypto15.randomUUID)() });
+  } catch (err) {
+    rethrowApplyError(err);
+  }
+  const data = result.body?.data ?? {};
+  if (ctx.format === "json") {
+    printJson(data);
+    return;
+  }
+  const succeeded = data.succeeded ?? [];
+  const failed = data.failed ?? [];
+  process.stdout.write(`Batch applied: ${succeeded.length} succeeded, ${failed.length} failed
+`);
+  for (const f of failed) {
+    process.stdout.write(`  #${f.index} ${sanitizeForTerminal(f.enc_job_id)}: ${sanitizeForTerminal(f.error_code)}
+`);
+  }
+}
+
 // src/commands/personal/index.ts
 function registerPersonalCommand(program2) {
-  const personal = program2.command("personal").description("Manage your personal resumes and profile");
+  const personal = program2.command("personal").description("Manage your personal resumes, profile and applications");
   registerPersonalResumesCommand(personal);
+  registerPersonalApplyCommand(personal);
 }
 
 // src/index.ts
 var program = new import_commander.Command();
-program.name("wport").description("wport CLI \u2014 terminal interface to the W101 Talent Search Hub public API").version("0.8.0", "-v, --version", "output the CLI version").option("--lang <locale>", "Accept-Language locale: zh-TW | en-US | vi-VN | th-TH | id-ID").option("--api <url>", "override API base URL").option("--output <fmt>", "output format: table | json").option("--no-color", "disable color output").option("--timeout <ms>", "HTTP timeout in milliseconds", (v) => Number(v));
+program.name("wport").description("wport CLI \u2014 terminal interface to the W101 Talent Search Hub public API").version("0.9.1-dev.0", "-v, --version", "output the CLI version").option("--lang <locale>", "Accept-Language locale: zh-TW | en-US | vi-VN | th-TH | id-ID").option("--api <url>", "override API base URL").option("--output <fmt>", "output format: table | json").option("--no-color", "disable color output").option("--timeout <ms>", "HTTP timeout in milliseconds", (v) => Number(v));
 registerJobsCommand(program);
 registerConfigCommand(program);
 registerDoctorCommand(program);