@synity/bitrix-skills 1.3.0

package/CHANGELOG.md

@@ -0,0 +1,169 @@
+# Changelog
+
+## 1.3.0
+
+### Minor Changes
+
+- 908b282: "bx:task v2.0 — 7-subcommand router with bootstrap/feature/roadmap"
+
+## 1.1.0
+
+### Minor Changes
+
+- **bx-task v1.1.0**: Add `sync` and `init` subcommands
+
+  - `sync [--task-id N]` — post session digest (git log + context) as Bitrix task comment
+  - `init [--task-id N]` — detect/insert TASK_ID block into nearest CLAUDE.md
+
+- **bx-crm skeleton**: Register `bx-crm` feature (planned — subcommands defined, not yet implemented)
+
+- **bx-calendar skeleton**: Register `bx-calendar` feature (planned — subcommands defined, not yet implemented)
+
+## 1.0.0
+
+### Major Changes
+
+- Initial v1.0.0 release. Multi-feature CLI for Bitrix24 + Claude Code integration.
+
+  Breaking changes vs `@synity/bitrix-task-sync@0.2.3`:
+
+  - Package renamed: `@synity/bitrix-task-sync` → `@synity/bitrix-tools`
+  - CLI binary renamed: `bitrix-task-sync` → `bitrix-tools`
+  - Install command: `npx bitrix-task-sync install` → `npx bitrix-tools install task-sync`
+  - Manifest file: `<project>/.bitrix-tools.json` (new, replaces ad-hoc detection)
+
+  New features:
+
+  - Multi-feature CLI: `task-sync` (project hooks) + `bx-task` (global skill)
+  - Interactive feature picker: `npx bitrix-tools install`
+  - `list`, `verify`, `update`, `uninstall` commands
+  - Shared TS + bash lib SSOT in `src/lib/`
+  - Extensible: add new Bitrix feature by creating `src/features/<name>/`
+
+  Migration guide: run `npx @synity/bitrix-tools install task-sync` in your project.
+
+All notable changes to `@synity/bitrix-task-sync` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.3] - 2026-05-10
+
+### Fixed
+
+- **Hooks not firing on every session — `session_id` resolution** (CRITICAL). `bitrix-skill-start.sh` and `bitrix-skill-end.sh` extracted `session_id` from PreToolUse/PostToolUse payloads, but Claude Code does NOT include `session_id` in those payloads (only `Stop` does). State landed at `<SESSION_DIR>/unknown.json`; Stop hook (which DOES get the real `session_id`) looked for `<real-id>.json`, missed it, and exited in <100ms with no digest, no time tracking, no token totals. Fix: fall back to `$CK_SESSION_ID` env var (already set by user-level `session-init.cjs` SessionStart hook). Applied identically to all 3 scripts (`bitrix-skill-start.sh`, `bitrix-skill-end.sh`, `bitrix-session-sync.sh`) so every hook resolves to the same SESSION_ID.
+
+  ```bash
+  # OLD: lands at unknown.json on PreToolUse/PostToolUse
+  SESSION_ID=$(echo "$PAYLOAD" | jq -r '.session_id // "unknown"')
+
+  # NEW: payload first, env fallback, then unknown
+  SESSION_ID=$(echo "$PAYLOAD" | jq -r '.session_id // empty')
+  SESSION_ID=${SESSION_ID:-${CK_SESSION_ID:-unknown}}
+  ```
+
+  Symptom user reported: brainstorm/plan/cook skills ran but Bitrix task chat received no comments. Verification post-fix: `ls /tmp/claude-b24/` shows `<real-session-id>.json` instead of `unknown.json`; Stop hook posts digest as expected.
+
+## [0.2.2] - 2026-05-10
+
+### Fixed
+
+- **Skill end hook function ordering** — `_attach_skill_artifacts()` was defined AFTER the `exit 0` early-return path; bash does not pre-parse functions past `exit`, so calls fired `command not found`. Moved definition above the early-return guard.
+- **Stop hook bash invocation** — `bitrix-render-digest.sh` lacks execute bit on fresh installs; Stop hook now prefixes with `bash` to avoid permission-denied on new clones.
+- **Worktree path detection** — `.git` is a file (not dir) in worktrees, breaking `git rev-parse --show-toplevel` for Drive root; now uses `--git-common-dir` to detect the shared main worktree path. Avoids per-worktree Drive folder fragmentation.
+- **Fallback JSONL probe** — when transcript path resolution fails, fallback glob now excludes `subagents/` directory and sorts newest-first, ensuring we read the parent session transcript (not a subagent's truncated log).
+- **Native task timer** — replaced manual `tasks.task.start` + `task.elapseditem.add` chain with native `tasks.task.startTimer` / `pauseTimer` (correct REST v2 method names). Removes one round-trip per skill, eliminates orphan time entries on crash.
+- **Stop hook redundant link** — removed duplicate `🔗 Task` line from digest header (now appears only at footer with task title).
+- **Skill output filter** — added `_has_useful_content()` guard before posting "skill xong" comments to prevent spam from skills that emit only JSON status / empty stdout (e.g. `git-manager`, `code-reviewer` returning structured-only output).
+- **Phase 3a checklist sync wiring** — `b24_sync_checklist` was implemented but never called from skill-end hook; added wire in `bitrix-skill-end.sh` after artifact attach so plan-emitted `bitrix-checklist` blocks now propagate to Bitrix.
+
+### Verified
+
+- Token tracking `UF_AI_TOKENS_TOTAL` accumulator working stably across full-day usage (no race conditions observed in single-developer scenario).
+
+### Build
+
+- `pnpm build` re-syncs assets from monorepo root + rebuilds `dist/`.
+
+### Companion
+
+- New global Claude Code skill `/bx:task` (separate install at `~/.claude/skills/bx-task/`) — manual KB summary posting (5 templates) + manual time entries. Complements the auto-sync hooks shipped here. See `README.md` "Companion: /bx:task skill".
+
+## [0.2.1] - 2026-05-10
+
+### Refactored
+
+- **BB code throughout** — replaced markdown templates with Bitrix BB code in `bitrix-skill-end.sh`, `bitrix-render-digest.sh`, `bitrix-lib.sh`. Headings → `[b]...[/b]`, bullets → `•`, code → `[code]...[/code]`. Markdown was rendering as literal text in Bitrix chat (cosmetic regression in 0.2.0).
+- **No-ceiling time format** — `_format_duration` now emits `5m 12s` (precise) instead of `6m` (ceiling). Hooks measure per-skill elapsed in integer seconds; ceiling lost up to 59s precision per skill.
+- **Approach C time tracking** — Stop hook now calls `task.elapseditem.add` ONCE per session with cumulative `elapsed_seconds`, instead of N times (one per PostToolUse). Reduces system-message spam from 2N to 2 per session. Orphan PostToolUse calls (no matching PreToolUse) are clamped to 0 to prevent the "29M phút" runaway bug.
+
+### Fixed
+
+- Webhook user identity confirmed as user 614 "Claude" (non-admin); rights.edit/remove = true on own posts → cleanup operations safe.
+
+## [0.2.0] - 2026-05-10
+
+### Added
+
+- **Token tracking** (`UF_AI_TOKENS_TOTAL` custom field) — `install` now calls `task.item.userfield.add` to create a numeric field on `TASKS_TASK`; Stop hook reads current value from transcript JSONL, accumulates `input + output` tokens, and writes back via `tasks.task.update`. Digest comment shows `🪙 Xk in / Yk out / Zk cached | task total: N tokens`.
+- **Time tracking lifecycle** — `bitrix-session-check.sh` (SessionStart) auto-enables `ALLOW_TIME_TRACKING` per task if not already set, posting a one-time audit comment with sentinel `[BTS-AUTO-TIMETRACK-V1]` to prevent spam. `bitrix-skill-start.sh` uses an atomic flock-based counter to call `tasks.task.start` on the first skill of a session; `bitrix-skill-end.sh` calls `tasks.task.pause` on the last. Stop hook force-pauses as crash-safety.
+- **File attach** — PostToolUse hook for `plan/planner/brainstorm/cook/research/journal` skills parses `\`\`\`bitrix-artifact\`\`\``fenced block from tool output (or falls back to glob of recently modified`.md`files), uploads to group/user drive via`disk.folder.uploadfile`, attaches to task via `tasks.task.files.attach`. Drive layout: `AI Sessions/<repo>/<rel-dir>/`.
+- **Cook completion digest** — Stop hook renders a full session summary: plan title + phase progress (checkbox ratio), skills + total minutes, token line, attached file list, and git commits since session start. Uses new pure-render helper `bitrix-render-digest.sh`.
+- **`verify` disk scope probe** — reports whether `disk` scope is available; warns clearly if missing (file-attach degrades gracefully, install still succeeds).
+- New scripts: `bitrix-attach-files.sh` (standalone attach orchestrator), `bitrix-render-digest.sh` (pure digest renderer).
+- New TS module: `src/lib/token-extractor.ts` — parses Claude Code transcript JSONL for token usage.
+- 17 new Vitest cases across 4 test files: `token-tracker`, `time-tracking`, `file-attach`, `digest-render`.
+
+### Changed
+
+- `bitrix-session-check.sh` — now writes `BTS_SESSION_START_ISO` to session env file for digest; probes task status on SessionStart (skips lifecycle if STATUS=5 closed); wipes stale skill counter.
+- `bitrix-skill-start.sh` — increments skill counter; calls `tasks.task.start` on 0→1 transition.
+- `bitrix-skill-end.sh` — decrements counter; calls `tasks.task.pause` on 1→0; triggers artifact attach for applicable skills.
+- `bitrix-session-sync.sh` — delegates rendering to `bitrix-render-digest.sh`; accumulates session tokens; force-pauses task; cleans up all session tmp files.
+- `bitrix-lib.sh` — added Phase 1–3 helpers: `b24_ensure_uf`, `b24_task_get_uf_tokens`, `b24_task_set_uf_tokens`, `_compute_session_tokens`, `b24_finalize_session_tokens`, `_skill_counter_incr/decr`, `b24_task_start/pause/status`, `b24_ensure_timetracking`, `b24_disk_get_root_folder`, `b24_disk_ensure_folder`, `b24_disk_upload`, `b24_task_attach_file`, `b24_attach_artifact`.
+
+### Notes
+
+- **Breaking:** webhook user now requires **edit-task** permission (previously comment-only was sufficient). Needed for `tasks.task.start/pause/update`.
+- **Known issue:** `tasks.task.file.attach` (v3) is broken on Bitrix portal with `Class "File" requires attribute "DtoType"` — shipping with legacy `tasks.task.files.attach`. Awaiting Bitrix support fix.
+- **Race condition (documented):** `UF_AI_TOKENS_TOTAL` accumulator is read-modify-write (not atomic). Two concurrent Stop hooks on the same task may lose one session's tokens. Acceptable for single-developer usage (one session at a time).
+
+## [0.1.1] - 2026-05-10
+
+### Fixed
+
+- **`b24_call` now streams curl response to stdout** instead of redirecting to `/dev/null` — `verify` smoke test (`/"result"/` regex) was always failing because the JSON response was discarded. Without this fix, `verify` exits 3 even when the webhook is healthy.
+
+### Added
+
+- **Skill ref counting** — `~/.claude/skills/bitrix-sync-install/` is now reference-counted via a sidecar `.refs.json`. Each `install` registers the project; `uninstall` removes shared skill files only when the last project unlinks, so uninstall in project A never breaks project B.
+- New `clearAllRefs` / `getSkillDir` / `getRefsFile` helpers in `lib/skill-refs.ts` (lazy path resolution for testability).
+- 10 new vitest cases for cross-project install/uninstall, idempotency, dry-run safety, and migration fallback.
+
+### Changed
+
+- `--remove-skill` now also clears the entire refs registry (previously would leave stale entries).
+- Empty registry + skill files present is treated as ambiguous (likely pre-ref-counting install) — files preserved unless `--remove-skill` is passed.
+
+## [0.1.0] - 2026-05-09
+
+### Added
+
+- Initial release of `@synity/bitrix-task-sync` — portable npm package + Claude Code skill for installing Bitrix Task Sync into any project via `npx`.
+- `install` command — copies 11 managed files (5 hook scripts, 2 githooks, 1 layer rule, 2 docs, 1 GitHub workflow) + merges 4 hook triggers into `.claude/settings.json`.
+- `uninstall` command — removes only sha256-matching files (preserves user modifications) + cleans Bitrix entries from settings without touching user hooks.
+- `verify` command — end-to-end smoke test: TASK_ID presence, `BITRIX_WEBHOOK_URL`, live webhook POST, manifest drift check. Distinct exit codes (1/2/3/4) per failure.
+- `update` command — alias for `install --force` to refresh managed files to current SSOT versions.
+- Build-time SSOT sync (`scripts/sync-assets.mjs`) — copies from monorepo root → `assets/` with sha256 manifest generation.
+- Idempotent settings merge using `deepmerge` with array dedup by `JSON.stringify`.
+- Brownfield-safe install — preserves existing `.claude/settings.json` user hooks, never modifies `CLAUDE.md`, skips user-modified files without `--force`.
+- Skill orchestrator at `~/.claude/skills/bitrix-sync-install/` — interactive 7-step Claude Code skill that runs the CLI on the user's behalf.
+- 18 vitest cases covering install (10), uninstall (4), and manifest drift (4) scenarios.
+
+### Notes
+
+- Requires Node.js >= 20.
+- Skill install uses `os.homedir()` (cross-platform), respects `--no-skill` for CI.
+- Live `npm publish` deferred until first downstream-app smoke test.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Synity Vietnam JSC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+# @synity/bitrix-skills
+
+[![npm version](https://img.shields.io/npm/v/@synity/bitrix-skills.svg)](https://www.npmjs.com/package/@synity/bitrix-skills)
+[![CI](https://github.com/synity-tech/bitrix-tools/actions/workflows/ci.yml/badge.svg)](https://github.com/synity-tech/bitrix-tools/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Multi-feature CLI for **Bitrix24 + Claude Code** integration — task sync hooks, skills, and more.
+
+---
+
+## Features
+
+| Feature | Target | Description |
+|---------|--------|-------------|
+| `task-sync` | project | AI session sync to Bitrix task chat via hooks |
+| `bx-task` | global (`~/.claude/skills`) | Claude Code skill for Bitrix task management |
+| `bx-crm` | global (`~/.claude/skills`) | Claude Code skill for CRM: contacts, deals, companies, analysis, reports |
+| `bx-calendar` | global (`~/.claude/skills`) | Claude Code skill for Calendar: meetings, reminders, availability, CRM sync |
+| `bx` | global (`~/.claude/skills`) | Hub router skill — discovery entry point for all bx:* skills |
+
+## Install
+
+```bash
+npx @synity/bitrix-skills install
+```
+
+Interactive picker. Or:
+
+```bash
+npx @synity/bitrix-skills install --all          # all features
+npx @synity/bitrix-skills install task-sync      # specific feature
+```
+
+## 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 --version
+```
+
+## Requirements
+
+- Node.js >= 20
+- `BITRIX_WEBHOOK_URL` env var (for `task-sync`)
+- `bitrix-synity-mcp` MCP server (for `bx-task` skill)
+
+## Quick start (task-sync)
+
+```bash
+# 1. Install into your project
+npx @synity/bitrix-skills install task-sync
+
+# 2. Set TASK_ID in CLAUDE.md
+echo -e "## Bitrix Task\nTASK_ID: 12345" >> CLAUDE.md
+
+# 3. Export webhook URL
+export BITRIX_WEBHOOK_URL="https://your-portal.bitrix24.com/rest/1/xxx/"
+
+# 4. Start Claude Code session - hooks fire automatically
+```
+
+## Migration from `@synity/bitrix-task-sync`
+
+See [docs/migration-from-bitrix-task-sync.md](docs/migration-from-bitrix-task-sync.md).
+
+## Documentation
+
+- [docs/feature-task-sync.md](docs/feature-task-sync.md)
+- [docs/feature-bx-task.md](docs/feature-bx-task.md)
+- [docs/architecture.md](docs/architecture.md)
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT (c) 2026 Synity Vietnam JSC

package/bin/bitrix-skills.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from '../dist/cli.js';
+run(process.argv.slice(2));