@k-msg/cli 0.7.1 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,76 @@
 # @k-msg/cli
 
+## 0.8.0 — 2026-02-21
+
+### Minor changes
+
+- [46c54c0](https://github.com/k-otp/k-msg/commit/46c54c059f004c34b0acf497a0d06343ff2b7d83) Refactor Kakao channel handling around `@k-msg/channel` runtime services and redesign CLI channel commands.
+  
+  ## `@k-msg/channel` (minor)
+  
+  - split exports into runtime-first root API and toolkit-only subpath (`@k-msg/channel/toolkit`)
+  - add runtime services:
+    - `KakaoChannelCapabilityService`
+    - `KakaoChannelBindingResolver`
+    - `KakaoChannelLifecycleService`
+  - add runtime channel binding/capability types:
+    - `KakaoChannelCapabilityMode`
+    - `KakaoChannelBinding`
+    - `ResolvedKakaoChannelBinding`
+    - `KakaoChannelListItem`
+  - add provider adapter flow for mode-specific handling (`aligo`, `iwinv`, `solapi`, `mock`)
+  
+  ## `@k-msg/cli` (minor)
+  
+  - replace legacy `kakao channel` direct provider flow with channel runtime services
+  - add `kakao channel binding` command group:
+    - `list`, `resolve`, `set`, `delete`
+  - add `kakao channel api` command group:
+    - `categories`, `list`, `auth`, `add`
+  - remove legacy `kakao channel categories|list|auth|add` behavior and return guided migration errors
+  - unify senderKey/plusId resolution with channel binding resolver (including provider config hints such as `solapi.kakaoPfId`) — Thanks @imjlk!
+- [adb3997](https://github.com/k-otp/k-msg/commit/adb3997754705ad24f7865e73e4bdff0f5a69360) Refactor template handling around `@k-msg/template` as the single runtime source of truth.
+  
+  ## `@k-msg/template` (minor)
+  
+  - introduce runtime-first API surface:
+    - `TemplateLifecycleService`
+    - `TemplatePersonalizer`, `defaultTemplatePersonalizer`, `TemplateVariableUtils`
+    - `validateTemplatePayload`, `parseTemplateButtons`
+  - split builder/registry/testing helpers to a dedicated subpath: `@k-msg/template/toolkit`
+  - remove legacy root exports that overlapped service semantics (`TemplateService`, `MockTemplateService`, root-level builder/registry exports)
+  - move personalization implementation from messaging into template package
+  
+  ## `@k-msg/messaging` (minor)
+  
+  - remove root personalization exports:
+    - `VariableReplacer`
+    - `VariableUtils`
+    - `defaultVariableReplacer`
+  - migration path: import the renamed equivalents from `@k-msg/template`
+    - `TemplatePersonalizer`
+    - `TemplateVariableUtils`
+    - `defaultTemplatePersonalizer`
+  
+  ## `@k-msg/cli` (minor)
+  
+  - route `kakao template *` commands through `TemplateLifecycleService` instead of direct provider template method calls
+  - apply template runtime validation (`validateTemplatePayload`, `parseTemplateButtons`) before provider requests for create/update flows
+  
+  ## `@k-msg/provider` (patch)
+  
+  - remove duplicate template interpolation path in Aligo send by reusing template runtime interpolation
+  - apply shared template payload/button validation to Aligo and IWINV template create/update flows
+  - normalize Aligo template button serialization through the shared template button parser/serializer — Thanks @imjlk!
+
+### Patch changes
+
+- [ce4bba0](https://github.com/k-otp/k-msg/commit/ce4bba07974365c681e29e6da2e007c968c84c74) Harden CLI installer and launcher path sync behavior to reduce unsafe overwrites across mixed install methods.
+  
+  - `install.sh` now skips replacing active symlink/script launchers (for example package-manager shims) and falls back to `~/.local/bin` unless `K_MSG_CLI_INSTALL_DIR` is explicitly set.
+  - The npm/bun launcher sync logic now targets only active command entries and only replaces native executables, avoiding broad PATH scanning and accidental script replacement. — Thanks @imjlk!
+- Updated dependencies: channel@0.20.0, core@0.20.0, messaging@0.20.0, provider@0.20.0, template@0.20.0, k-msg@0.20.0
+
 ## 0.7.1 — 2026-02-21
 
 ### Patch changes

package/README.md

@@ -18,6 +18,10 @@ Note: the npm package downloads a native binary from GitHub Releases on first ru
 using `checksums.txt`, then extracts and caches it under your OS cache directory
 (`K_MSG_CLI_CACHE_DIR` to override).
 
+When a new native binary is installed, the launcher also performs best-effort sync
+for writable legacy `k-msg` binaries found on PATH (for example, older curl-based
+installs). Set `K_MSG_CLI_SYNC_PATHS=0` to disable this behavior.
+
 Env overrides:
 
 - `K_MSG_CLI_BASE_URL`: override GitHub release base URL (default: `https://github.com/k-otp/k-msg/releases/download/cli-v<version>`)
@@ -33,9 +37,14 @@ curl -fsSL https://k-otp.github.io/k-msg/cli/install.sh | bash
 Installer environment variables:
 
 - `K_MSG_CLI_VERSION`: override target version (default: latest Pages script version)
-- `K_MSG_CLI_INSTALL_DIR`: target directory (default: `~/.local/bin`)
+- `K_MSG_CLI_INSTALL_DIR`: target directory override (default: auto-detect active `k-msg` directory when writable, otherwise `~/.local/bin`)
 - `K_MSG_CLI_BASE_URL`: override release base URL (default: `https://github.com/k-otp/k-msg/releases/download/cli-v<version>`)
 
+Path conflict note:
+
+- The installer now prefers updating the currently active `k-msg` path when possible, and also refreshes that path if it differs from the selected install dir. This reduces stale-version issues when users previously installed via `bun`/`npm`/older `curl` flows.
+- For safety, the installer does not overwrite active symlink/script launchers (for example package-manager shims). In that case it installs to `~/.local/bin` unless `K_MSG_CLI_INSTALL_DIR` is set.
+
 ### GitHub Releases (manual)
 
 The distribution workflow also publishes prebuilt binaries to GitHub Releases as:
@@ -178,9 +187,15 @@ Required values by provider/channel:
 - `k-msg alimtalk preflight|send`
 - `k-msg send --input <json> | --file <path> | --stdin` (advanced/raw JSON only)
 - `k-msg db schema print|generate`
-- `k-msg kakao channel categories|list|auth|add`
+- `k-msg kakao channel binding list|resolve|set|delete`
+- `k-msg kakao channel api categories|list|auth|add`
 - `k-msg kakao template list|get|create|update|delete|request`
 
+Template command internals:
+
+- `kakao template *` commands route through `TemplateLifecycleService` from `@k-msg/template`.
+- `create/update` validate `name/content/buttons` using `validateTemplatePayload` + `parseTemplateButtons` before provider API calls.
+
 ## DB schema generator
 
 Generate canonical SQL DDL and/or Drizzle schema source from the same
@@ -320,13 +335,21 @@ Resolution precedence for overlapping values is:
 
 - `CLI flag > environment variable > config file > built-in default`
 
-## Kakao Channel (Aligo capability)
+## Kakao Channel
 
 ```bash
-k-msg kakao channel categories
-k-msg kakao channel list
-k-msg kakao channel auth --plus-id @my_channel --phone 01012345678
-k-msg kakao channel add \
+# config/provider-hint binding management (works for api/manual/none providers)
+k-msg kakao channel binding list
+k-msg kakao channel binding resolve --channel main
+k-msg kakao channel binding set --alias main --provider aligo-main --sender-key SENDER_KEY --plus-id @my_channel
+k-msg kakao channel binding delete --alias old-channel
+
+# provider API operations (api-mode providers only, e.g. aligo/mock)
+k-msg kakao channel api categories --provider aligo-main
+k-msg kakao channel api list --provider aligo-main
+k-msg kakao channel api auth --provider aligo-main --plus-id @my_channel --phone 01012345678
+k-msg kakao channel api add \
+  --provider aligo-main \
   --plus-id @my_channel \
   --auth-num 123456 \
   --phone 01012345678 \
@@ -334,6 +357,8 @@ k-msg kakao channel add \
   --save main
 ```
 
+Legacy notice: `k-msg kakao channel categories|list|auth|add` were removed. The CLI now prints guidance to the new `binding` / `api` command groups.
+
 ## Kakao Template (IWINV/Aligo)
 
 Channel scope (Aligo): use `--channel <alias>` or `--sender-key <value>`.

package/bin/k-msg.js

@@ -139,6 +139,176 @@ function parseChecksums(text) {
   return out;
 }
 
+function safeRealpath(filePath) {
+  try {
+    return fs.realpathSync(filePath);
+  } catch {
+    return null;
+  }
+}
+
+function isWritableFile(filePath) {
+  try {
+    fs.accessSync(filePath, fs.constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function parseVersionFromOutput(output) {
+  const m = /\bk-msg v([0-9]+\.[0-9]+\.[0-9]+)\b/.exec(output);
+  return m ? m[1] : null;
+}
+
+function readCommandVersion(commandPath) {
+  const result = spawnSync(commandPath, ["--version"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: 3000,
+  });
+  if (result.error || result.status !== 0) return null;
+  const output = `${result.stdout || ""}\n${result.stderr || ""}`;
+  return parseVersionFromOutput(output);
+}
+
+function resolveActiveCommand(commandName) {
+  const pathValue = process.env.PATH || "";
+  const dirs = pathValue.split(path.delimiter).filter(Boolean);
+  const suffixes =
+    process.platform === "win32" ? [".exe", ".cmd", ".bat", ""] : [""];
+
+  for (const dir of dirs) {
+    for (const suffix of suffixes) {
+      const candidate = path.join(dir, `${commandName}${suffix}`);
+      if (fs.existsSync(candidate)) {
+        return candidate;
+      }
+    }
+  }
+
+  return null;
+}
+
+function listActiveCommandCandidates() {
+  const seen = new Set();
+  const out = [];
+  for (const name of ["k-msg", "kmsg"]) {
+    const resolved = resolveActiveCommand(name);
+    if (!resolved || seen.has(resolved)) continue;
+    seen.add(resolved);
+    out.push(resolved);
+  }
+  return out;
+}
+
+function isLikelyNativeExecutable(filePath) {
+  let fd;
+  try {
+    fd = fs.openSync(filePath, "r");
+    const buffer = Buffer.alloc(4);
+    const read = fs.readSync(fd, buffer, 0, 4, 0);
+    if (read < 2) return false;
+
+    // ELF
+    if (
+      read >= 4 &&
+      buffer[0] === 0x7f &&
+      buffer[1] === 0x45 &&
+      buffer[2] === 0x4c &&
+      buffer[3] === 0x46
+    ) {
+      return true;
+    }
+
+    // Mach-O (32/64, little/big endian)
+    if (read >= 4) {
+      const magic = buffer.readUInt32BE(0);
+      if (
+        magic === 0xfeedface ||
+        magic === 0xfeedfacf ||
+        magic === 0xcefaedfe ||
+        magic === 0xcffaedfe
+      ) {
+        return true;
+      }
+    }
+
+    // PE/COFF (Windows)
+    if (buffer[0] === 0x4d && buffer[1] === 0x5a) {
+      return true;
+    }
+  } catch {
+    return false;
+  } finally {
+    if (typeof fd === "number") {
+      try {
+        fs.closeSync(fd);
+      } catch {
+        // ignore
+      }
+    }
+  }
+
+  return false;
+}
+
+function replaceBinary({ sourcePath, targetPath }) {
+  const tmpPath = `${targetPath}.kmsg-sync-${process.pid}.tmp`;
+  fs.copyFileSync(sourcePath, tmpPath);
+  if (process.platform !== "win32") {
+    fs.chmodSync(tmpPath, 0o755);
+  }
+  fs.renameSync(tmpPath, targetPath);
+}
+
+function syncLegacyCommandPaths({ binaryPath, version }) {
+  const syncOptOut = process.env.K_MSG_CLI_SYNC_PATHS;
+  if (
+    typeof syncOptOut === "string" &&
+    ["0", "false", "off"].includes(syncOptOut.trim().toLowerCase())
+  ) {
+    return;
+  }
+
+  const selfScript = safeRealpath(process.argv[1] || "");
+  const binaryReal = safeRealpath(binaryPath);
+  const updated = [];
+
+  for (const candidate of listActiveCommandCandidates()) {
+    let stat;
+    try {
+      stat = fs.lstatSync(candidate);
+    } catch {
+      continue;
+    }
+
+    if (!stat.isFile() || stat.isSymbolicLink()) continue;
+    if (!isWritableFile(candidate)) continue;
+    if (!isLikelyNativeExecutable(candidate)) continue;
+
+    const candidateReal = safeRealpath(candidate);
+    if (candidateReal && selfScript && candidateReal === selfScript) continue;
+    if (candidateReal && binaryReal && candidateReal === binaryReal) continue;
+
+    const currentVersion = readCommandVersion(candidate);
+    if (!currentVersion || currentVersion === version) continue;
+
+    try {
+      replaceBinary({ sourcePath: binaryPath, targetPath: candidate });
+      updated.push({ path: candidate, from: currentVersion });
+    } catch {
+      // Best-effort sync: ignore per-path failures.
+    }
+  }
+
+  for (const item of updated) {
+    console.error(
+      `[k-msg] Synced existing install: ${item.path} (${item.from} -> ${version})`,
+    );
+  }
+}
+
 function tarReadString(header, start, len) {
   const slice = header.subarray(start, start + len);
   const zero = slice.indexOf(0);
@@ -194,7 +364,9 @@ async function ensureBinary() {
   const cacheDir = path.join(cacheBaseDir(), "k-msg", "cli", version, target);
   const dest = path.join(cacheDir, `k-msg${ext}`);
 
-  if (fs.existsSync(dest)) return dest;
+  if (fs.existsSync(dest)) {
+    return { binaryPath: dest, version, freshlyInstalled: false };
+  }
 
   const local = process.env.K_MSG_CLI_LOCAL_BINARY;
   if (typeof local === "string" && local.trim().length > 0) {
@@ -203,7 +375,7 @@ async function ensureBinary() {
     if (process.platform !== "win32") {
       fs.chmodSync(dest, 0o755);
     }
-    return dest;
+    return { binaryPath: dest, version, freshlyInstalled: true };
   }
 
   const baseUrl =
@@ -247,7 +419,7 @@ async function ensureBinary() {
       fs.chmodSync(dest, 0o755);
     }
     fs.rmSync(archiveTmp, { force: true });
-    return dest;
+    return { binaryPath: dest, version, freshlyInstalled: true };
   } catch (err) {
     fs.rmSync(archiveTmp, { force: true });
     fs.rmSync(binTmp, { force: true });
@@ -256,7 +428,12 @@ async function ensureBinary() {
 }
 
 async function main() {
-  const bin = await ensureBinary();
+  const resolved = await ensureBinary();
+  syncLegacyCommandPaths({
+    binaryPath: resolved.binaryPath,
+    version: resolved.version,
+  });
+  const bin = resolved.binaryPath;
   const result = spawnSync(bin, process.argv.slice(2), { stdio: "inherit" });
   if (result.error) {
     console.error(result.error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k-msg/cli",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "private": false,
   "description": "k-msg CLI (prebuilt binaries via GitHub Releases)",
   "type": "module",
@@ -33,16 +33,18 @@
     "clean": "rm -rf dist"
   },
   "devDependencies": {
-    "@k-msg/core": "0.18.2",
-    "@k-msg/messaging": "0.18.2",
-    "@k-msg/provider": "0.18.2",
+    "@k-msg/channel": "0.19.1",
+    "@k-msg/core": "0.19.1",
+    "@k-msg/messaging": "0.19.1",
+    "@k-msg/provider": "0.19.1",
+    "@k-msg/template": "0.19.1",
     "@bunli/core": "^0.5.4",
     "@bunli/plugin-ai-detect": "^0.5.2",
     "@bunli/test": "^0.3.2",
     "@types/bun": "^1.3.9",
     "@types/node": "^22.0.0",
     "bunli": "^0.5.3",
-    "k-msg": "0.18.2",
+    "k-msg": "0.19.1",
     "solapi": "^5.5.4",
     "typescript": "^5.7.2",
     "zod": "^4.0.14"