@synity/bitrix-skills 1.3.0

package/src/features/task-sync/index.ts

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import kleur from 'kleur';
+import { getVersion } from './lib/version.js';
+import * as install from './commands/install.js';
+import * as uninstall from './commands/uninstall.js';
+import * as verify from './commands/verify.js';
+import * as update from './commands/update.js';
+import type { CliOptions } from './types.js';
+
+const USAGE = `
+  ${kleur.bold('bitrix-skills')} — Synity Bitrix24 tooling CLI
+
+  ${kleur.bold('Usage:')}
+    npx @synity/bitrix-skills <command> [options]
+
+  ${kleur.bold('Commands:')}
+    install      Copy hooks/scripts/docs + merge .claude/settings.json
+    uninstall    Reverse install (removes managed files, cleans settings)
+    verify       Smoke test live Bitrix webhook (requires TASK_ID + BITRIX_WEBHOOK_URL)
+    update       Re-install managed files only (force overwrite, preserves user files)
+
+  ${kleur.bold('Options:')}
+    --cwd=<path>      Project root (default: auto-detect via .git/ or pnpm-workspace.yaml)
+    --dry-run         Print planned actions, no FS changes
+    --force           Overwrite user-modified managed files (install/update)
+    --no-githooks     Skip .githooks/ + commit-msg setup (install)
+    --no-workflow     Skip .github/workflows/bitrix-sync.yml (install)
+    --no-skill        Skip ~/.claude/skills/bitrix-sync-install (install)
+    --keep-docs       Preserve docs/bitrix-task-*.md (uninstall)
+    --remove-skill    Also remove ~/.claude/skills/bitrix-sync-install (uninstall, default: preserve)
+    --quiet           Skip live webhook call (verify — env + manifest only)
+    --version, -v     Print version
+    --help, -h        Print this help
+
+  ${kleur.bold('Examples:')}
+    npx @synity/bitrix-skills install
+    npx @synity/bitrix-skills install --dry-run
+    npx @synity/bitrix-skills verify
+    npx @synity/bitrix-skills uninstall
+`;
+
+function parseCli(): { command: string | undefined; opts: CliOptions; help: boolean; version: boolean } {
+  const { values, positionals } = parseArgs({
+    args: process.argv.slice(2),
+    allowPositionals: true,
+    options: {
+      cwd: { type: 'string' },
+      'dry-run': { type: 'boolean', default: false },
+      force: { type: 'boolean', default: false },
+      'no-githooks': { type: 'boolean', default: false },
+      'no-workflow': { type: 'boolean', default: false },
+      'no-skill': { type: 'boolean', default: false },
+      'keep-docs': { type: 'boolean', default: false },
+      'remove-skill': { type: 'boolean', default: false },
+      quiet: { type: 'boolean', default: false },
+      version: { type: 'boolean', short: 'v', default: false },
+      help: { type: 'boolean', short: 'h', default: false },
+    },
+  });
+
+  const opts: CliOptions = {
+    cwd: (values['cwd'] as string | undefined) ?? process.cwd(),
+    dryRun: values['dry-run'] as boolean,
+    force: values['force'] as boolean,
+    noGithooks: values['no-githooks'] as boolean,
+    noWorkflow: values['no-workflow'] as boolean,
+    noSkill: values['no-skill'] as boolean,
+    keepDocs: values['keep-docs'] as boolean,
+    removeSkill: values['remove-skill'] as boolean,
+    quiet: values['quiet'] as boolean,
+  };
+
+  return {
+    command: positionals[0],
+    opts,
+    help: values['help'] as boolean,
+    version: values['version'] as boolean,
+  };
+}
+
+async function main(): Promise<number> {
+  const { command, opts, help, version } = parseCli();
+
+  if (version) {
+    const v = await getVersion();
+    console.log(v);
+    return 0;
+  }
+
+  if (help) {
+    console.log(USAGE);
+    return 0;
+  }
+  if (!command) {
+    console.log(USAGE);
+    return 2;
+  }
+
+  switch (command) {
+    case 'install':
+      return install.run(opts);
+    case 'uninstall':
+      return uninstall.run(opts);
+    case 'verify':
+      return verify.run(opts);
+    case 'update':
+      return update.run(opts);
+    default:
+      console.error(kleur.red(`unknown command: ${command}`));
+      console.log(USAGE);
+      return 2;
+  }
+}
+
+main()
+  .then((code) => process.exit(code))
+  .catch((err) => {
+    console.error(kleur.red(`\n  fatal: ${err instanceof Error ? err.message : String(err)}\n`));
+    process.exit(1);
+  });

package/src/features/task-sync/lib/dest-map.ts

@@ -0,0 +1,96 @@
+// Map manifest entry src (assets-relative) → project-relative dest path.
+// Single source of truth for both install and uninstall logic.
+import path from 'node:path';
+import os from 'node:os';
+import { assertContainedIn } from '../../../lib/fs-safety.js';
+import type { ManifestEntry, CliOptions } from '../types.js';
+
+export interface DestEntry {
+  manifestEntry: ManifestEntry;
+  destAbs: string;          // absolute path on FS
+  destRel: string;          // human-readable rel path for output
+  category: 'script' | 'githook' | 'rule' | 'doc' | 'workflow' | 'skill';
+  optionalFlag?: keyof CliOptions; // skip if this opt is true
+}
+
+export function buildDestMap(
+  manifest: { files: ManifestEntry[] },
+  cwd: string,
+): DestEntry[] {
+  const out: DestEntry[] = [];
+  const home = os.homedir();
+  const skillsRoot = path.join(home, '.claude', 'skills');
+
+  for (const entry of manifest.files) {
+    const src = entry.src;
+    if (src.startsWith('scripts/')) {
+      const name = src.slice('scripts/'.length);
+      const destRel = path.posix.join('.claude/scripts', name);
+      out.push({
+        manifestEntry: entry,
+        destAbs: path.resolve(cwd, destRel),
+        destRel,
+        category: 'script',
+      });
+    } else if (src.startsWith('githooks/')) {
+      const name = src.slice('githooks/'.length);
+      const destRel = path.posix.join('.githooks', name);
+      out.push({
+        manifestEntry: entry,
+        destAbs: path.resolve(cwd, destRel),
+        destRel,
+        category: 'githook',
+        optionalFlag: 'noGithooks',
+      });
+    } else if (src.startsWith('rules/')) {
+      const name = src.slice('rules/'.length);
+      const destRel = path.posix.join('.claude/rules', name);
+      out.push({
+        manifestEntry: entry,
+        destAbs: path.resolve(cwd, destRel),
+        destRel,
+        category: 'rule',
+      });
+    } else if (src.startsWith('docs/')) {
+      const name = src.slice('docs/'.length);
+      const destRel = path.posix.join('docs', name);
+      out.push({
+        manifestEntry: entry,
+        destAbs: path.resolve(cwd, destRel),
+        destRel,
+        category: 'doc',
+      });
+    } else if (src.startsWith('workflows/')) {
+      const name = src.slice('workflows/'.length);
+      const destRel = path.posix.join('.github/workflows', name);
+      out.push({
+        manifestEntry: entry,
+        destAbs: path.resolve(cwd, destRel),
+        destRel,
+        category: 'workflow',
+        optionalFlag: 'noWorkflow',
+      });
+    } else if (src.startsWith('skill/')) {
+      const name = src.slice('skill/'.length);
+      // Skill installs to user home (per Phase 04 spec): ~/.claude/skills/bitrix-sync-install/
+      const destAbs = path.resolve(home, '.claude', 'skills', 'bitrix-sync-install', name);
+      const destRel = path.posix.join('~/.claude/skills/bitrix-sync-install', name);
+      out.push({
+        manifestEntry: entry,
+        destAbs,
+        destRel,
+        category: 'skill',
+        optionalFlag: 'noSkill',
+      });
+    }
+    // Unknown prefix: silently ignore (forward-compatible)
+  }
+
+  // Containment check: guards against path-traversal in manifest entries.
+  for (const e of out) {
+    const allowedRoot = e.category === 'skill' ? skillsRoot : cwd;
+    assertContainedIn(e.destAbs, allowedRoot, e.manifestEntry.src);
+  }
+
+  return out;
+}

package/src/features/task-sync/lib/drift-check.ts

@@ -0,0 +1,47 @@
+// Compare each managed file's sha256 vs manifest expectation.
+// Returns drifted (modified content) and missing entries separately.
+import type { Manifest, CliOptions } from '../types.js';
+import { fileExists, sha256File } from './file-ops.js';
+import { buildDestMap } from './dest-map.js';
+
+export interface DriftEntry {
+  path: string;
+  reason: 'modified' | 'missing';
+  expected: string;
+  actual: string | null;
+}
+
+export async function checkDrift(
+  manifest: Manifest,
+  cwd: string,
+  opts: Partial<CliOptions> = {},
+): Promise<DriftEntry[]> {
+  const drifted: DriftEntry[] = [];
+  const dests = buildDestMap(manifest, cwd);
+
+  for (const d of dests) {
+    // Skip categories opted out
+    if (d.optionalFlag && opts[d.optionalFlag]) continue;
+
+    if (!(await fileExists(d.destAbs))) {
+      drifted.push({
+        path: d.destRel,
+        reason: 'missing',
+        expected: d.manifestEntry.sha256,
+        actual: null,
+      });
+      continue;
+    }
+    const actual = await sha256File(d.destAbs);
+    if (actual !== d.manifestEntry.sha256) {
+      drifted.push({
+        path: d.destRel,
+        reason: 'modified',
+        expected: d.manifestEntry.sha256,
+        actual,
+      });
+    }
+  }
+
+  return drifted;
+}

package/src/features/task-sync/lib/file-ops.ts

@@ -0,0 +1,36 @@
+// File system helpers: sha256, existence check, atomic write.
+import { createHash } from 'node:crypto';
+import { readFile, access, mkdir, writeFile, rename, chmod } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import path from 'node:path';
+
+export async function sha256File(filePath: string): Promise<string> {
+  const buf = await readFile(filePath);
+  return createHash('sha256').update(buf).digest('hex');
+}
+
+export function sha256Buffer(buf: Buffer | Uint8Array): string {
+  return createHash('sha256').update(buf).digest('hex');
+}
+
+export async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await access(filePath, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function ensureDir(dirPath: string): Promise<void> {
+  await mkdir(dirPath, { recursive: true });
+}
+
+// Atomic write: write to temp file, then rename. Avoids partial writes.
+export async function atomicWrite(filePath: string, content: string | Buffer, mode = 0o644): Promise<void> {
+  await ensureDir(path.dirname(filePath));
+  const tmp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  await writeFile(tmp, content, { mode });
+  await chmod(tmp, mode);
+  await rename(tmp, filePath);
+}

package/src/features/task-sync/lib/manifest.ts

@@ -0,0 +1,66 @@
+// Load + validate assets/manifest.json relative to package install location.
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { Manifest } from '../types.js';
+import { fileExists } from './file-ops.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Resolve the task-sync feature assets/ dir (contains hook scripts + manifest.json).
+// This code gets inlined into dist/cli.js (__dirname = dist/) AND dist/features/task-sync/index.js
+// (__dirname = dist/features/task-sync/). Both paths must be covered by the candidates below.
+export function resolveAssetsDir(): string {
+  const candidates = [
+    // From dist/ (cli.js context): ../src/features/task-sync/assets
+    path.resolve(__dirname, '../src/features/task-sync/assets'),
+    // From dist/features/task-sync/ (index.js context): ../../../src/features/task-sync/assets
+    path.resolve(__dirname, '../../../src/features/task-sync/assets'),
+    // Dev: src/features/task-sync/lib/ → ../assets
+    path.resolve(__dirname, '../assets'),
+    // Legacy fallbacks (should not match before correct paths above)
+    path.resolve(__dirname, '../../assets'),
+    path.resolve(__dirname, '../../../assets'),
+    path.resolve(__dirname, '../../../../assets'),
+  ];
+  for (const c of candidates) {
+    if (existsSync(path.join(c, 'manifest.json'))) {
+      return c;
+    }
+  }
+  // Fallback to first candidate; loadManifest will throw clearer error
+  return candidates[0]!;
+}
+
+export async function loadManifest(): Promise<Manifest> {
+  const dir = resolveAssetsDir();
+  const manifestPath = path.join(dir, 'manifest.json');
+  if (!(await fileExists(manifestPath))) {
+    throw new Error(`assets/manifest.json not found at ${manifestPath} (was 'pnpm build' run?)`);
+  }
+  const raw = await readFile(manifestPath, 'utf8');
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`malformed manifest.json: ${(err as Error).message}`);
+  }
+  validateManifest(parsed);
+  return parsed as Manifest;
+}
+
+function validateManifest(obj: unknown): asserts obj is Manifest {
+  if (!obj || typeof obj !== 'object') throw new Error('manifest must be an object');
+  const m = obj as Record<string, unknown>;
+  if (typeof m['version'] !== 'string') throw new Error('manifest.version must be string');
+  if (!Array.isArray(m['files'])) throw new Error('manifest.files must be array');
+  for (const f of m['files']) {
+    if (!f || typeof f !== 'object') throw new Error('manifest.files[] entry must be object');
+    const e = f as Record<string, unknown>;
+    if (typeof e['src'] !== 'string') throw new Error('manifest entry.src must be string');
+    if (typeof e['sha256'] !== 'string') throw new Error('manifest entry.sha256 must be string');
+    if (typeof e['size'] !== 'number') throw new Error('manifest entry.size must be number');
+    if (typeof e['mode'] !== 'number') throw new Error('manifest entry.mode must be number');
+  }
+}

package/src/features/task-sync/lib/project-root.ts

@@ -0,0 +1,38 @@
+// Walk up from cwd looking for project root markers (.git/, pnpm-workspace.yaml, package.json).
+import path from 'node:path';
+import { fileExists } from './file-ops.js';
+
+const ROOT_MARKERS = ['.git', 'pnpm-workspace.yaml'];
+
+export async function detectProjectRoot(startDir: string): Promise<string> {
+  let dir = path.resolve(startDir);
+  const root = path.parse(dir).root;
+  while (true) {
+    for (const marker of ROOT_MARKERS) {
+      if (await fileExists(path.join(dir, marker))) {
+        return dir;
+      }
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir || dir === root) {
+      break;
+    }
+    dir = parent;
+  }
+  // Fallback: if no marker found, walk up looking for any package.json
+  dir = path.resolve(startDir);
+  while (true) {
+    if (await fileExists(path.join(dir, 'package.json'))) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  // Last resort: use the original cwd (allows install in empty/fresh dirs)
+  return path.resolve(startDir);
+}
+
+export async function hasGitDir(rootDir: string): Promise<boolean> {
+  return fileExists(path.join(rootDir, '.git'));
+}

package/src/features/task-sync/lib/settings-merge.ts

@@ -0,0 +1,112 @@
+// .claude/settings.json deep-merge + Bitrix hook subtraction.
+// Idempotent: merging template twice yields the same result (dedup by JSON identity).
+import { readFile } from 'node:fs/promises';
+import deepmerge from 'deepmerge';
+import { fileExists, atomicWrite } from './file-ops.js';
+
+export interface ClaudeHookEntry {
+  matcher?: string;
+  hooks?: Array<{ type?: string; command?: string }>;
+}
+
+export interface ClaudeSettings {
+  hooks?: {
+    SessionStart?: ClaudeHookEntry[];
+    PreToolUse?: ClaudeHookEntry[];
+    PostToolUse?: ClaudeHookEntry[];
+    Stop?: ClaudeHookEntry[];
+    [key: string]: ClaudeHookEntry[] | undefined;
+  };
+  [key: string]: unknown;
+}
+
+// Template: 4 hooks Bitrix Task Sync registers.
+// Commands reference scripts at runtime; full hook keys / matchers MUST exactly match
+// to enable idempotent merge + clean uninstall subtraction.
+export const BITRIX_HOOKS_TEMPLATE: ClaudeSettings = {
+  hooks: {
+    SessionStart: [
+      { hooks: [{ type: 'command', command: 'bash .claude/scripts/bitrix-session-check.sh' }] },
+    ],
+    PreToolUse: [
+      { matcher: 'Skill', hooks: [{ type: 'command', command: 'bash .claude/scripts/bitrix-skill-start.sh' }] },
+    ],
+    PostToolUse: [
+      { matcher: 'Skill', hooks: [{ type: 'command', command: 'bash .claude/scripts/bitrix-skill-end.sh' }] },
+    ],
+    Stop: [
+      { hooks: [{ type: 'command', command: 'bash .claude/scripts/bitrix-session-sync.sh' }] },
+    ],
+  },
+};
+
+// Custom array merge: concat then dedupe by serialized JSON.
+// Edge case: identical entries → kept once (idempotent re-install).
+// Edge case: same matcher but different command → both preserved (user has multiple hooks).
+function arrayMerge<T>(target: T[], source: T[]): T[] {
+  const combined = [...target, ...source];
+  const seen = new Set<string>();
+  const result: T[] = [];
+  for (const item of combined) {
+    const key = JSON.stringify(item);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    result.push(item);
+  }
+  return result;
+}
+
+export function mergeSettings(existing: ClaudeSettings, template: ClaudeSettings): ClaudeSettings {
+  return deepmerge(existing, template, {
+    arrayMerge,
+    clone: true,
+  }) as ClaudeSettings;
+}
+
+export async function loadSettingsFile(filePath: string): Promise<ClaudeSettings> {
+  if (!(await fileExists(filePath))) return {};
+  const raw = await readFile(filePath, 'utf8');
+  if (!raw.trim()) return {};
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      throw new Error('settings.json must be a JSON object');
+    }
+    return parsed as ClaudeSettings;
+  } catch (err) {
+    throw new Error(`malformed settings.json (${filePath}): ${(err as Error).message}`);
+  }
+}
+
+export async function writeSettingsFile(filePath: string, obj: ClaudeSettings): Promise<void> {
+  const json = JSON.stringify(obj, null, 2) + '\n';
+  await atomicWrite(filePath, json, 0o644);
+}
+
+// Predicate: a hook entry was installed by us (matches Bitrix script command pattern).
+function isBitrixHookEntry(entry: ClaudeHookEntry): boolean {
+  const cmds = (entry.hooks ?? []).map((h) => h.command).filter((c): c is string => typeof c === 'string');
+  return cmds.some((c) => /\.claude\/scripts\/bitrix-/.test(c));
+}
+
+// Strip Bitrix hooks from settings — preserves user's other hooks.
+// Empties trigger array → removes trigger key. Empties hooks object → removes hooks key.
+export function removeBitrixHooks(settings: ClaudeSettings): ClaudeSettings {
+  const cloned: ClaudeSettings = JSON.parse(JSON.stringify(settings));
+  const hooks = cloned.hooks;
+  if (!hooks) return cloned;
+  for (const trigger of Object.keys(hooks)) {
+    const list = hooks[trigger];
+    if (!Array.isArray(list)) continue;
+    const filtered = list.filter((entry) => !isBitrixHookEntry(entry));
+    if (filtered.length === 0) {
+      delete hooks[trigger];
+    } else {
+      hooks[trigger] = filtered;
+    }
+  }
+  if (Object.keys(hooks).length === 0) {
+    delete cloned.hooks;
+  }
+  return cloned;
+}

package/src/features/task-sync/lib/skill-refs.ts

@@ -0,0 +1,106 @@
+// User-scope skill is installed once at ~/.claude/skills/bitrix-sync-install/
+// and shared across every Synity project on the machine. We track which
+// projects have referenced it via a sidecar refs.json so uninstall in one
+// project never breaks another.
+//
+// Paths are resolved lazily via getters so tests can override HOME at runtime
+// to keep the user's real ~/.claude tree untouched.
+import { readFile, writeFile, mkdir, rm, access } from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+
+export function getSkillDir(): string {
+  return path.join(os.homedir(), '.claude/skills/bitrix-sync-install');
+}
+
+export function getRefsFile(): string {
+  return path.join(getSkillDir(), '.refs.json');
+}
+
+interface SkillRefs {
+  version: 1;
+  projects: string[];
+}
+
+async function loadRefs(): Promise<SkillRefs> {
+  try {
+    const raw = await readFile(getRefsFile(), 'utf8');
+    const parsed = JSON.parse(raw) as unknown;
+    if (
+      parsed &&
+      typeof parsed === 'object' &&
+      Array.isArray((parsed as SkillRefs).projects)
+    ) {
+      return { version: 1, projects: [...(parsed as SkillRefs).projects] };
+    }
+  } catch {
+    // missing or malformed → start fresh
+  }
+  return { version: 1, projects: [] };
+}
+
+async function saveRefs(refs: SkillRefs): Promise<void> {
+  await mkdir(getSkillDir(), { recursive: true });
+  await writeFile(getRefsFile(), JSON.stringify(refs, null, 2) + '\n', 'utf8');
+}
+
+// Add a project path to the refs set. Returns the post-add list.
+// Idempotent — re-adding an existing path is a no-op.
+export async function addProjectRef(projectPath: string): Promise<string[]> {
+  const abs = path.resolve(projectPath);
+  const refs = await loadRefs();
+  if (!refs.projects.includes(abs)) {
+    refs.projects.push(abs);
+    await saveRefs(refs);
+  }
+  return refs.projects;
+}
+
+// Remove a project from the refs set. Returns:
+//   { remaining: number, removed: boolean }
+// `removed: true` only if the project was previously listed.
+export async function removeProjectRef(
+  projectPath: string,
+): Promise<{ remaining: number; removed: boolean }> {
+  const abs = path.resolve(projectPath);
+  const refs = await loadRefs();
+  const before = refs.projects.length;
+  refs.projects = refs.projects.filter((p) => p !== abs);
+  const removed = refs.projects.length < before;
+  if (refs.projects.length === 0) {
+    // Caller decides whether to delete the directory. We just clear refs.
+    try {
+      await rm(getRefsFile(), { force: true });
+    } catch {
+      // non-fatal
+    }
+  } else if (removed) {
+    await saveRefs(refs);
+  }
+  return { remaining: refs.projects.length, removed };
+}
+
+export async function getRefs(): Promise<string[]> {
+  const refs = await loadRefs();
+  return refs.projects;
+}
+
+// Wipes the skill directory + refs sidecar entirely. Used when --remove-skill is passed —
+// the user has chosen to nuke the shared directory regardless of who
+// else still references it.
+export async function clearAllRefs(): Promise<void> {
+  try {
+    await rm(getSkillDir(), { recursive: true, force: true });
+  } catch {
+    // non-fatal
+  }
+}
+
+export async function skillDirExists(): Promise<boolean> {
+  try {
+    await access(getSkillDir());
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/features/task-sync/lib/task-id-finder.ts

@@ -0,0 +1,31 @@
+// TS port of bash `find_task_id` from .claude/scripts/bitrix-lib.sh.
+// Walks up from startDir looking for `TASK_ID:` line in CLAUDE.md.
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileExists } from './file-ops.js';
+
+export async function findTaskId(startDir: string): Promise<string | null> {
+  let dir = path.resolve(startDir);
+  const root = path.parse(dir).root;
+  while (true) {
+    const md = path.join(dir, 'CLAUDE.md');
+    if (await fileExists(md)) {
+      const content = await readFile(md, 'utf8');
+      const match = content.match(/^TASK_ID:\s*(\S+)/m);
+      if (match && match[1]) {
+        // Strip trailing CR (CRLF files) — \S in JS regex matches CR
+        return match[1].replace(/\r$/, '');
+      }
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir || dir === root) break;
+    dir = parent;
+  }
+  return null;
+}
+
+// TASK_ID must be numeric (Bitrix task ID). Reject anything else to prevent
+// shell injection when later passed to `bash -c`.
+export function isValidTaskId(taskId: string): boolean {
+  return /^\d+$/.test(taskId);
+}