@synity/bitrix-skills 1.3.5 → 1.3.7

package/CHANGELOG.md

@@ -1,18 +1,22 @@
 # Changelog
 
-## 1.3.5
+## 1.3.7
 
 ### Patch Changes
 
-- fix(install): add generic handler for target:global skill features (bx, bx-crm, bx-calendar)
+- fix(task-sync): add missing assets/skill/SKILL.md that caused ENOENT on update
 
-  Previously, installing bx, bx-crm, or bx-calendar printed "No install handler" and exited with failure. All three are target:global features — their assets now get copied to ~/.claude/skills/{name}/ via a new installGlobalSkill() helper that resolves the assets dir relative to the package root across all build contexts.
+  docs(task-sync): document --key flag and fix stale package name (@synity/bitrix-task-sync → @synity/bitrix-skills) in SKILL.md and README to prevent agent hallucinating --token flag
 
 ## 1.3.1
 
 ### Patch Changes
 
-- bx-crm: add optional deal products flow to onboard.md — findProducts → setDealProducts after createDealWithParties. Fix findProducts param (query→name), document substring keyword behavior, note Commerce catalog scope requirement.
+- dfe3549: fix: mark stub features (bx, bx-calendar, bx-crm) as `planned`
+
+  Previously these features had `status: "active"` in feature.json but no install handler wired into `src/commands/install.ts`, causing `install --all` to print `! No install handler for feature: <name>` for each.
+
+  Now they're filtered out by the existing `f.status !== 'planned'` check (install.ts:121). Will flip back to `active` when install handlers land.
 
 ## 1.3.0
 

package/README.md

@@ -31,15 +31,28 @@ npx @synity/bitrix-skills install --all          # all features
 npx @synity/bitrix-skills install task-sync      # specific feature
 ```
 
+### Paid features (`task-sync`)
+
+`task-sync` requires a license key to unlock:
+
+```bash
+npx @synity/bitrix-skills install task-sync --key <your-license-key>
+```
+
+Free tier installs all other features (`bx`, `bx-task`, `bx-crm`, `bx-calendar`) without a key.
+
+> **Note:** The flag is `--key`, not `--token`.
+
 ## Commands
 
 ```bash
-bitrix-skills install [features...]   # install with picker or by name
-bitrix-skills install --all           # install all features
-bitrix-skills list                    # show available + installed status
-bitrix-skills verify                  # verify installed file checksums
-bitrix-skills update                  # update installed features to latest
-bitrix-skills uninstall <feature>     # remove a feature
+bitrix-skills install [features...]          # install with picker or by name
+bitrix-skills install --all                  # install all features
+bitrix-skills install task-sync --key <key>  # install paid feature with license key
+bitrix-skills list                           # show available + installed status
+bitrix-skills verify                         # verify installed file checksums
+bitrix-skills update                         # update installed features to latest
+bitrix-skills uninstall <feature>            # remove a feature
 bitrix-skills --version
 ```
 

package/dist/cli.js

@@ -947,11 +947,8 @@ init_esm_shims();
 import { Command, Option } from "clipanion";
 import chalk from "chalk";
 import { existsSync as existsSync4 } from "fs";
-import { access as access4, mkdir as mkdir4, copyFile as copyFile3, readdir as readdir2 } from "fs/promises";
 import { createInterface } from "readline";
-import { dirname as dirname3, join as join4, relative as relative2, resolve as resolve2 } from "path";
-import { fileURLToPath as fileURLToPath5 } from "url";
-import { homedir as homedir2 } from "os";
+import { join as join4, relative as relative2 } from "path";
 
 // src/lib/feature-registry.ts
 init_esm_shims();
@@ -1049,11 +1046,11 @@ function computeChecksum(filepath) {
 
 // src/commands/install.ts
 function promptKey() {
-  return new Promise((resolve3) => {
+  return new Promise((resolve2) => {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     rl.question(chalk.cyan("License key (Enter to skip \u2014 free tier only): "), (answer) => {
       rl.close();
-      resolve3(answer.trim());
+      resolve2(answer.trim());
     });
   });
 }
@@ -1089,55 +1086,6 @@ async function installTaskSync(cwd) {
     return { ok: false, message: `task-sync: ${err.message}` };
   }
 }
-async function getGlobalSkillAssetsDir(name) {
-  const here = dirname3(fileURLToPath5(import.meta.url));
-  const candidates = [
-    resolve2(here, `../../src/features/${name}/assets`),
-    // dist/commands/install.js
-    resolve2(here, `../src/features/${name}/assets`),
-    // dist/cli.js (inlined bundle)
-    resolve2(here, `../features/${name}/assets`)
-    // src/commands/ (dev/ts-node)
-  ];
-  for (const c of candidates) {
-    try {
-      await access4(c);
-      return c;
-    } catch {
-    }
-  }
-  return candidates[0];
-}
-async function copyDirRecursive(srcDir, destDir, files) {
-  await mkdir4(destDir, { recursive: true });
-  const entries = await readdir2(srcDir, { withFileTypes: true });
-  for (const entry of entries) {
-    const srcPath = join4(srcDir, entry.name);
-    const destPath = join4(destDir, entry.name);
-    if (entry.isDirectory()) {
-      await copyDirRecursive(srcPath, destPath, files);
-    } else {
-      await copyFile3(srcPath, destPath);
-      files.push(destPath);
-    }
-  }
-}
-async function installGlobalSkill(name) {
-  const skillDest = resolve2(homedir2(), ".claude", "skills", name);
-  const installedAbsPaths = [];
-  try {
-    const assetsDir = await getGlobalSkillAssetsDir(name);
-    await copyDirRecursive(assetsDir, skillDest, installedAbsPaths);
-    return {
-      ok: true,
-      message: `${name}: ${installedAbsPaths.length} files \u2192 ${skillDest}`,
-      installPath: skillDest,
-      installedAbsPaths
-    };
-  } catch (err) {
-    return { ok: false, message: `${name}: ${err.message}`, installPath: skillDest, installedAbsPaths };
-  }
-}
 async function installBxTask(cwd) {
   try {
     const { install: install2 } = await Promise.resolve().then(() => (init_install2(), install_exports2));
@@ -1259,15 +1207,10 @@ Installing ${chalk.bold(name)}...
         ok = r.ok;
         message = r.message;
         if (r.installPath) {
-          installPath = resolve2(homedir2(), ".claude", "skills", "bx-task");
+          const { homedir: homedir2 } = await import("os");
+          installPath = join4(homedir2(), ".claude", "skills", "bx-task");
         }
         installedAbsPaths = r.installedAbsPaths ?? [];
-      } else if (featureInfo.target === "global") {
-        const r = await installGlobalSkill(name);
-        ok = r.ok;
-        message = r.message;
-        installPath = r.installPath;
-        installedAbsPaths = r.installedAbsPaths;
       } else {
         this.context.stderr.write(chalk.yellow(`  ! No install handler for feature: ${name}
 `));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synity/bitrix-skills",
-  "version": "1.3.5",
+  "version": "1.3.7",
   "description": "Multi-feature Bitrix24 tooling CLI for Synity projects",
   "type": "module",
   "bin": {

package/src/features/bx/feature.json

@@ -4,6 +4,7 @@
   "version": "1.0.0",
   "target": "global",
   "description": "Claude Code hub skill \u2014 routes to bx:crm, bx:task, bx:calendar. Install for discovery UX.",
+  "status": "planned",
   "requires": {},
   "tier": 0
 }

package/src/features/bx-calendar/feature.json

@@ -4,6 +4,7 @@
   "version": "1.0.0",
   "target": "global",
   "description": "Claude Code skill for Bitrix24 Calendar: meetings, reminders, team availability, CRM activity sync",
+  "status": "planned",
   "requires": {
     "env": [
       "BITRIX_WEBHOOK_URL"

package/src/features/bx-crm/assets/SKILL.md

@@ -15,7 +15,7 @@ Use this skill for CRM entities only: contacts, companies, deals, leads, estimat
 
 | User intent | Load file | Key helpers |
 |---|---|---|
-| create/update contact, company, deal, lead | `onboard.md` | `upsertContact`, `upsertCompanyByTaxCode`, `createDealWithParties`, `setDealProducts`, `findProducts` |
+| create/update contact, company, deal, lead | `onboard.md` | `upsertContact`, `upsertCompanyByTaxCode`, `createDealWithParties` |
 | VN phone, honorific, address, MST format | `vn-norms.md` | normalization rules |
 | convert/qualify lead to deal | `convert.md` | `convertLeadToDeal` |
 | estimate, báo giá, invoice, payment link | `commerce.md` | `createEstimate`, `approveEstimate`, `createSmartInvoice` |

package/src/features/bx-crm/assets/onboard.md

@@ -69,42 +69,6 @@ Timeline: <start date>
 Notes: <context>
 ```
 
-## Deal — Optional Products
-
-Add products only when the user explicitly mentions product names or asks for products on the deal.
-
-```js
-// 1. Extract short keyword (1-2 words) from user's product name — do NOT pass full name
-// name = substring match; "%keyword%" wildcard syntax breaks the param
-const matches = await findProducts({ name: "<short keyword>", limit: 5 })
-// → [{ id, name, sku, price, currency, vatRate, matched }]
-
-// 2. Confirm match with user if multiple or ambiguous results
-// 3. Add to deal (currency omitted — Bitrix inherits from deal)
-await setDealProducts({
-  dealId,
-  items: [{ productId: matches[0].id, price: matches[0].price, quantity: 1 }],
-  mode: "replace"
-})
-```
-
-**MCP gap fallback** — use only when `setDealProducts` is absent from `codemode.catalog()`:
-```js
-codemode.request({
-  method: "POST",
-  path: "/crm.deal.productrows.set",
-  body: { id: dealId, rows: [{ PRODUCT_ID: id, PRICE: price, QUANTITY: quantity }] }
-})
-```
-
-**Rules:**
-- Products are optional — add only when user mentions specific product names.
-- Always `findProducts` to resolve name → id; never hardcode `PRODUCT_ID`.
-- Pass a short keyword (1-2 words) to `findProducts({ name })`, not the full product name.
-- Omit `currency` in items — Bitrix inherits it from the deal automatically.
-- Custom line items (no catalog id): pass `{ name, price, quantity }` without `id`.
-- Commerce catalog variants (SKU variants) require `catalog` scope on the MCP token; if 401, fall back to custom line item and note the MCP gap.
-
 ## Lead — Create + Products
 
 Use lead when the prospect is unqualified or missing deal-level budget/timeline.
@@ -165,7 +129,6 @@ Omit `idempotencyKey`. **Verified 2026-05-15:** D1 table `idempotency_keys` miss
 - [ ] Contact: VN phone stored with `+84`; HONORIFIC matches [vn-norms.md](./vn-norms.md).
 - [ ] Company: `RQ_VAT_ID` populated, address entity exists, MST format valid.
 - [ ] Deal: `STAGE_ID` set, `OPPORTUNITY > 0`, payer linked.
-- [ ] Deal (with products): products set; `OPPORTUNITY` matches product total.
 - [ ] Lead: `SOURCE_ID` set, phone/email present, products set when user requested products.
 - [ ] Update: only intended fields changed.
 

package/src/features/bx-crm/feature.json

@@ -4,6 +4,7 @@
   "version": "2.0.0",
   "target": "global",
   "description": "Claude Code skill for Bitrix24 CRM: contacts, companies, deals, leads, estimates, invoices, customer analysis, pipeline reports",
+  "status": "planned",
   "requires": {
     "mcp": [
       "bitrix-synity-mcp"

package/src/features/task-sync/assets/manifest.json

@@ -100,8 +100,8 @@
     },
     {
       "src": "skill/SKILL.md",
-      "sha256": "e9e4072710b43695354b4d1d31d002625778e8f1330b4e5666d0c0f9d6cd2303",
-      "size": 5208,
+      "sha256": "c9c954308515242f9c4c9d935a6bb456d4b3fee10513dc9e7c835d61bf10ff27",
+      "size": 6230,
       "mode": 420
     }
   ]

package/src/features/task-sync/assets/skill/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: bitrix-sync-install
+description: |
+  Install Bitrix Task Sync vào brownfield project (existing repo).
+  Wraps `npx @synity/bitrix-skills` với interactive TASK_ID setup,
+  webhook env var detection, và live verify smoke test.
+
+  Use when:
+  - User says "install bitrix sync", "setup task tracking", "thêm bitrix sync vào dự án"
+  - User asks how to enable AI session sync to Bitrix24 task chat
+  - Brownfield project not scaffolded by `create-bitrix-app`
+tools: [Bash, Read, Edit, AskUserQuestion]
+---
+
+# /bitrix-sync-install — Install Bitrix Task Sync (interactive)
+
+Orchestrate installation of [@synity/bitrix-skills](https://www.npmjs.com/package/@synity/bitrix-skills) into the current project. **Skill = thin wrapper** — all file copy / settings merge / githook setup is delegated to the npm CLI. Skill only handles interactive bits CLI cannot do (CLAUDE.md edit, env var detection, user confirmation gates).
+
+> **IMPORTANT — flag names:** The CLI uses `--key` for license key. There is NO `--token` flag. Using `--token` causes `Unknown Syntax Error`. Always use `--key`.
+
+## Workflow (7 steps with user confirmation)
+
+### Step 1 — Detect project state
+
+Run via Bash to inspect current dir:
+
+```bash
+pwd && ls -la .claude .githooks docs CLAUDE.md 2>/dev/null
+```
+
+Show user what already exists. **Decision:**
+- If `.claude/scripts/bitrix-*.sh` already exists → skip to Step 7 (verify only)
+- Else → proceed Step 2
+
+### Step 2 — Preflight check
+
+Confirm bash deps present:
+
+```bash
+command -v jq && command -v curl && command -v awk && echo "OK"
+```
+
+If any missing → abort, instruct user to install (`brew install jq` on macOS).
+
+### Step 3 — Dry-run install
+
+Check if user has a license key:
+
+```bash
+# Ask user: "Bạn có license key cho task-sync không?" (optional)
+```
+
+Dry-run:
+
+```bash
+# Without key (free tier — installs bx, bx-task, bx-crm, bx-calendar; skips task-sync):
+npx -y @synity/bitrix-skills install task-sync --dry-run
+
+# With key (unlocks task-sync):
+npx -y @synity/bitrix-skills install task-sync --key <license-key> --dry-run
+```
+
+Show planned actions.
+
+> **Flag:** `--key` — NOT `--token`. There is no `--token` flag in this CLI.
+
+### Step 4 — Confirm + install
+
+Use `AskUserQuestion`:
+
+```
+Question: "Proceed with install? (review the dry-run plan above)"
+Options:
+  - "Yes, install" — runs `npx ... install`
+  - "No, abort" — exit skill
+```
+
+If yes:
+
+```bash
+# Without key:
+npx -y @synity/bitrix-skills install task-sync
+
+# With key:
+npx -y @synity/bitrix-skills install task-sync --key <license-key>
+```
+
+### Step 5 — TASK_ID setup
+
+Read `CLAUDE.md` (project root). Search for `TASK_ID:` pattern.
+
+**Missing case:**
+1. `AskUserQuestion` for `PORTAL` URL (e.g. `https://yourname.bitrix24.com`)
+2. `AskUserQuestion` for `TASK_ID` (numeric task ID from Bitrix24 task URL)
+3. Validate `TASK_ID` is numeric (reject `1234abc`)
+4. Use `Edit` to insert at end of CLAUDE.md:
+
+```markdown
+
+## Bitrix Task
+
+PORTAL: {portal_url}
+TASK_ID: {task_id}
+
+<!-- AI session activity auto-syncs to this task via .claude/scripts/bitrix-*.sh hooks -->
+<!-- See docs/bitrix-task-sync.md for setup details -->
+```
+
+**Present case:** display existing TASK_ID + ask user to confirm or update.
+
+### Step 6 — Webhook env var
+
+Check current shell env:
+
+```bash
+[ -n "$BITRIX_WEBHOOK_URL" ] && echo SET || echo UNSET
+```
+
+If `UNSET`, `AskUserQuestion`:
+
+```
+Question: "Where to add BITRIX_WEBHOOK_URL?"
+Options:
+  - ".envrc (direnv)"
+  - "~/.zshrc"
+  - "~/.bashrc"
+  - "Skip — I'll do it manually"
+```
+
+Print the exact `export` command. Wait for user to confirm they ran `source <file>` (or restarted shell). **NEVER auto-edit shell rc files** — could conflict with user's setup.
+
+Example output:
+```
+Add this line to ~/.zshrc:
+  export BITRIX_WEBHOOK_URL="https://yourname.bitrix24.com/rest/USER_ID/TOKEN/"
+Then run: source ~/.zshrc
+
+(Press confirm when done)
+```
+
+### Step 7 — Verify
+
+```bash
+npx -y @synity/bitrix-skills verify
+```
+
+Interpret exit codes:
+
+| Code | Meaning | User Action |
+|------|---------|-------------|
+| 0 | Success — comment posted | Done. |
+| 1 | TASK_ID missing in CLAUDE.md | Re-run Step 5 |
+| 2 | BITRIX_WEBHOOK_URL not set | Re-run Step 6 |
+| 3 | Webhook call failed (network/token error) | Verify webhook URL is correct + has perms |
+| 4 | Manifest drift detected | Run `npx @synity/bitrix-skills update` to repair |
+
+## Final summary
+
+On success, print:
+
+```
+✓ Bitrix Task Sync installed and verified
+
+Next: every commit must include [B24:{TASK_ID}] tag, e.g.:
+  feat: implement deal sync [B24:{task_id}]
+
+AI activity (skills) auto-syncs to: {portal_url}/company/personal/user/USER/tasks/task/view/{task_id}/
+```
+
+## Failure modes
+
+| Symptom | Likely cause | Fix |
+|---------|--------------|-----|
+| `command not found: jq` | macOS without homebrew | `brew install jq curl` |
+| `npx: not found` | Node not installed | Install Node 20+ from nodejs.org |
+| `git: not a repository` | Not in git repo | `git init` first |
+| Webhook returns 401 | Bad token | Regenerate webhook in Bitrix24 → Apps → Webhooks |
+| `TASK_ID: 1234abc` rejected | Non-numeric value | Use ID from task URL, e.g. `12345` |
+| `Unknown Syntax Error: Invalid option name ("--token=...")` | Used `--token` instead of `--key` | **Always use `--key <value>`, never `--token`** |
+| `task-sync: paid feature, key invalid` | License key not recognized | Verify key is correct; free tier skips task-sync |
+
+## Re-run behavior
+
+Re-running on already-installed project:
+- Step 1 detects existing `.claude/scripts/bitrix-*.sh`
+- Skips to Step 7 (verify only)
+- If verify passes → "Already installed and working"
+- If verify fails → suggests `npx @synity/bitrix-skills update`
+
+## Notes
+
+- **Package name**: `@synity/bitrix-skills` (NOT `@synity/bitrix-task-sync` — that is the old deprecated package).
+- **License key flag**: `--key <value>` — there is NO `--token` flag. Using `--token` throws `Unknown Syntax Error`.
+- **Project-scope only**: skill operates on current cwd's git root. Does NOT touch other projects.
+- **Idempotent**: re-run = no-op if state is good.
+- **No secrets logged**: skill never echoes `BITRIX_WEBHOOK_URL` value, only its set/unset status.