Skip to content
Back to search

yadisk-sync

Yandex Disk WebDAV sync for apps — a production-tested reference module (TypeScript/Capacitor and Kotlin/Android) plus an OpenCode skill. Data-safety rules included: no empty-DB overwrite, snapshot before replace, keep the last N copies.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/vladimirgorodok--yadisk-sync/badge.svg)](/listings/vladimirgorodok--yadisk-sync)

HTML

<a href="/listings/vladimirgorodok--yadisk-sync"><img src="/api/listings/vladimirgorodok--yadisk-sync/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Add the skill and command to OpenCode

git clone https://github.com/vladimirgorodok/yadisk-sync
cd yadisk-sync

mkdir -p ~/.config/opencode/skills/yadisk-sync/scripts ~/.config/opencode/commands
cp skill/SKILL.md            ~/.config/opencode/skills/yadisk-sync/SKILL.md
cp skill/scripts/install.mjs ~/.config/opencode/skills/yadisk-sync/scripts/install.mjs
cp commands/sync-setup.md    ~/.config/opencode/commands/sync-setup.md

2. Expose the reference module to OpenCode

In `~/.config/opencode/opencode.json` (or `opencode.jsonc`):

{
  "references": {
    "sync-kit": {
      "repository": "https://github.com/vladimirgorodok/yadisk-sync",
      "description": "Yandex Disk WebDAV sync reference module (TS/Capacitor and Kotlin)"
    }
  }
}

A local checkout works too — use `path` instead of `repository`:

{ "references": { "sync-kit": { "path": "~/work/yadisk-sync" } } }

3. Use it

Open a session in your project and run `/sync-setup` (or ask "@yadisk-sync, add Yandex Disk sync"). The skill will:

1. detect your stack and where data, settings, and images live; 2. read `PROTOCOL.md`, `CHECKLIST.md`, and the stack's `TOUCHPOINTS.md`; 3. show a plan and **change nothing without your confirmation**; 4. lay the files down:

   node ~/.config/opencode/skills/yadisk-sync/scripts/install.mjs --lang ts --project . --dry-run

(`--dry-run` only prints the plan; without it, files are copied without overwriting, and the cloud file prefix and package are rewritten for your project. Also useful: `--prefix`, `--package`, `--force`.) 5. replace the touchpoints and wire the entry points; 6. run the acceptance list from `CHECKLIST.md` and report what was verified and what was not.

4. Package it for a marketplace

The same skill ships as a self-contained ZIP for agent marketplaces (Agensi and any platform that follows the open SKILL.md format):

node scripts/build-skill-package.mjs      # → dist/yadisk-sync.zip

Listing copy for Agensi is ready to paste from [`packaging/agensi-listing.md`](packaging/agensi-listing.md).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 245 lines
  1. <p align="center">
  2. <img src="assets/logo-256.png" width="128" height="128" alt="yadisk-sync logo">
  3. </p>
  4. <h1 align="center">yadisk-sync</h1>
  5. <p align="center">
  6. <b>App data ⇄ Yandex Disk over WebDAV.</b><br>
  7. A ready-to-drop reference module for <b>TypeScript/Capacitor</b> and <b>Kotlin/Android</b> apps —
  8. plus an <b>OpenCode skill</b> that wires it into your project for you.
  9. </p>
  10. <p align="center">
  11. <a href="https://github.com/vladimirgorodok/yadisk-sync/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-2563EB.svg" alt="License: MIT"></a>
  12. <img src="https://img.shields.io/badge/OpenCode-skill-111827.svg" alt="OpenCode skill">
  13. <img src="https://img.shields.io/badge/TypeScript-Capacitor-3178C6.svg?logo=typescript&logoColor=white" alt="TypeScript">
  14. <img src="https://img.shields.io/badge/Kotlin-Android-7F52FF.svg?logo=kotlin&logoColor=white" alt="Kotlin">
  15. <img src="https://img.shields.io/badge/WebDAV-Yandex%20Disk-FB5607.svg" alt="WebDAV">
  16. <img src="https://img.shields.io/badge/requires-Yandex%20360-FFCC00.svg" alt="Requires Yandex 360">
  17. </p>
  18. <p align="center">
  19. <b>English</b> · <a href="README.ru.md">Русский</a>
  20. </p>
  21. <p align="center">
  22. <img src="assets/social-preview.png" alt="yadisk-sync" width="820">
  23. </p>
  24. ---
  25. ## Why
  26. Cloud backup on Android is a swamp. OAuth providers want app registration and keys, sync APIs want SDKs,
  27. and "just upload a file" quietly turns into a week of plumbing — while one bad run can overwrite a user's
  28. only good copy with an empty database.
  29. `yadisk-sync` removes that week. It talks to **Yandex Disk over plain WebDAV**
  30. (`https://webdav.yandex.ru`) with an **app password** — no app registration, no OAuth keys — and ships
  31. the data-safety rules that stop a sync from destroying data.
  32. It is not a sketch. The reference code is a **byte-for-byte copy of two apps running in production**:
  33. - **Avtotracker** — TypeScript + Capacitor;
  34. - **Platezhi2** — Kotlin + native Android.
  35. ## What you get
  36. | | |
  37. |---|---|
  38. | 🔁 **Two implementations** | TypeScript/Capacitor and Kotlin/native Android, same protocol, same file format. |
  39. | 🧩 **Drop-in reference module** | `core` copies as-is; `project-example` is the integration you adapt, with every touchpoint documented. |
  40. | 🤖 **OpenCode skill + command** | Ask `/sync-setup` (or "@yadisk-sync, add Yandex Disk sync"). It reads the docs, shows a plan, and wires the module in. |
  41. | 🛡️ **Data-safety rules built in** | Never push an empty DB over a non-empty one, snapshot before a "replace" restore, keep the last N copies, quiet errors. |
  42. | 🖼️ **Icons as a separate archive** | The data file stays tiny; images ship as a ZIP only when they actually change (hash-compared). |
  43. | 📄 **Full protocol documentation** | Methods, XML parsing, failure codes, file naming, settings keys, and every project touchpoint. |
  44. ## Architecture
  45. The same exchange in both stacks:
  46. ```mermaid
  47. flowchart LR
  48. subgraph App["Your app"]
  49. UI["Sync screen<br/>(login, app password, folder, keep-N)"]
  50. DATA["Data layer<br/>tables + settings"]
  51. ICONS["Images / icons"]
  52. AUTO["Auto-sync<br/>on change · on launch · on background"]
  53. end
  54. subgraph Module["sync-kit module"]
  55. CORE["core<br/>WebDAV client, XML, errors"]
  56. PROJ["project-example<br/>push / pull / icons / safety"]
  57. end
  58. DISK[("Yandex Disk<br/>webdav.yandex.ru")]
  59. UI --> PROJ
  60. DATA --> PROJ
  61. ICONS --> PROJ
  62. AUTO --> PROJ
  63. PROJ --> CORE
  64. CORE -- "PROPFIND · MKCOL · PUT · GET · DELETE" --> DISK
  65. DISK -- "&lt;prefix&gt;-YYYY-MM-DD_HHmmss.json<br/>&lt;prefix&gt;-icons-YYYY-MM-DD_HHmmss.zip" --> PROJ
  66. ```
  67. Two files land in your chosen folder on Disk:
  68. ```
  69. <prefix>-2026-11-20_143012.json data: every table + settings you cannot lose
  70. <prefix>-2026-11-20_143012.zip icons: images and document photos, only when changed
  71. ```
  72. ## Repository layout
  73. ```
  74. .
  75. ├── README.md ← you are here (English)
  76. ├── README.ru.md ← Русский
  77. ├── LICENSE ← MIT
  78. ├── assets/ ← logo, social preview
  79. ├── sync-kit/ ← the reference module (per-stack docs, core, project-example)
  80. │ ├── PROTOCOL.md ← how the exchange works: WebDAV, files, safety
  81. │ ├── CHECKLIST.md ← port it to a new project, step by step + acceptance list
  82. │ ├── ts/ ← TypeScript/Capacitor: core, project-example, native Android plugin
  83. │ └── kotlin/ ← Kotlin/native Android: core, project-example
  84. ├── skill/ ← OpenCode skill "yadisk-sync"
  85. │ ├── SKILL.md
  86. │ └── scripts/install.mjs ← lays the module files into a project
  87. ├── commands/sync-setup.md ← the /sync-setup command
  88. ├── packaging/ ← marketplace listing copy (Agensi)
  89. └── scripts/build-skill-package.mjs ← builds a self-contained skill .zip for marketplaces
  90. ```
  91. The code under `sync-kit/*/core` and `sync-kit/*/project-example` is a **byte-for-byte copy** of the
  92. production apps. It is never edited by hand — that is what keeps the reference trustworthy. Everything
  93. that is "project-specific" is listed in `sync-kit/ts/TOUCHPOINTS.md` and `sync-kit/kotlin/TOUCHPOINTS.md`.
  94. ## Quick start
  95. ### 1. Add the skill and command to OpenCode
  96. ```bash
  97. git clone https://github.com/vladimirgorodok/yadisk-sync
  98. cd yadisk-sync
  99. mkdir -p ~/.config/opencode/skills/yadisk-sync/scripts ~/.config/opencode/commands
  100. cp skill/SKILL.md ~/.config/opencode/skills/yadisk-sync/SKILL.md
  101. cp skill/scripts/install.mjs ~/.config/opencode/skills/yadisk-sync/scripts/install.mjs
  102. cp commands/sync-setup.md ~/.config/opencode/commands/sync-setup.md
  103. ```
  104. ### 2. Expose the reference module to OpenCode
  105. In `~/.config/opencode/opencode.json` (or `opencode.jsonc`):
  106. ```jsonc
  107. {
  108. "references": {
  109. "sync-kit": {
  110. "repository": "https://github.com/vladimirgorodok/yadisk-sync",
  111. "description": "Yandex Disk WebDAV sync reference module (TS/Capacitor and Kotlin)"
  112. }
  113. }
  114. }
  115. ```
  116. A local checkout works too — use `path` instead of `repository`:
  117. ```jsonc
  118. { "references": { "sync-kit": { "path": "~/work/yadisk-sync" } } }
  119. ```
  120. ### 3. Use it
  121. Open a session in your project and run `/sync-setup` (or ask "@yadisk-sync, add Yandex Disk sync").
  122. The skill will:
  123. 1. detect your stack and where data, settings, and images live;
  124. 2. read `PROTOCOL.md`, `CHECKLIST.md`, and the stack's `TOUCHPOINTS.md`;
  125. 3. show a plan and **change nothing without your confirmation**;
  126. 4. lay the files down:
  127. ```bash
  128. node ~/.config/opencode/skills/yadisk-sync/scripts/install.mjs --lang ts --project . --dry-run
  129. ```
  130. (`--dry-run` only prints the plan; without it, files are copied without overwriting, and the cloud
  131. file prefix and package are rewritten for your project. Also useful: `--prefix`, `--package`, `--force`.)
  132. 5. replace the touchpoints and wire the entry points;
  133. 6. run the acceptance list from `CHECKLIST.md` and report what was verified and what was not.
  134. ### 4. Package it for a marketplace
  135. The same skill ships as a self-contained ZIP for agent marketplaces (Agensi and any platform that follows
  136. the open SKILL.md format):
  137. ```bash
  138. node scripts/build-skill-package.mjs # → dist/yadisk-sync.zip
  139. ```
  140. Listing copy for Agensi is ready to paste from [`packaging/agensi-listing.md`](packaging/agensi-listing.md).
  141. ## Manual use (no agent)
  142. 1. Read `sync-kit/CHECKLIST.md` and tick off what your project already has (settings store, JSON
  143. export/import, image storage).
  144. 2. Copy `sync-kit/ts/core` or `sync-kit/kotlin/core` — **as is**.
  145. 3. Copy `project-example` and replace the project touchpoints using `TOUCHPOINTS.md`.
  146. 4. Verify: "Check connection", push, pull, empty-DB guard, background flush.
  147. ## Data-safety rules (the important part)
  148. These are not decoration — without them, sync corrupts data:
  149. 1. **An empty DB is never pushed over a non-empty one.** Local row count vs. cloud row count is
  150. compared first; upload stops with an explanation.
  151. 2. **A snapshot is taken before a "replace" restore.** Merge is the safe default; replace is not.
  152. 3. **The last N copies are kept** (default 5); older ones are deleted.
  153. 4. **Errors are quiet.** The message stays on the sync screen — no modal windows, no crashes.
  154. 5. **Your own uploads are not pulled back.** Push time and filename are remembered; the just-uploaded
  155. file is ignored during auto-sync (a ~10 s quiet window).
  156. ## Requirements
  157. - **Yandex app password**, not the account password. For WebDAV, create a password of type *Files*
  158. (or *WebDAV client*): <https://id.yandex.ru/security/app-passwords>.
  159. - **Yandex 360 subscription** — Disk is exposed over WebDAV to subscribers.
  160. - On Android, `PROPFIND` and `MKCOL` do **not** pass through the Capacitor HTTP bridge; the TypeScript
  161. stack ships a native OKHttp plugin (`sync-kit/ts/android/WebDavPlugin.java`).
  162. - Sync **cannot work in a browser** (Yandex CORS). The app must say so in words instead of failing silently.
  163. ## Documentation
  164. | Document | What it covers |
  165. |---|---|
  166. | [`sync-kit/PROTOCOL.md`](sync-kit/PROTOCOL.md) | WebDAV methods, XML parsing, error codes, file format, safety rules, auto-sync |
  167. | [`sync-kit/CHECKLIST.md`](sync-kit/CHECKLIST.md) | Porting order and the acceptance list |
  168. | [`sync-kit/ts/TOUCHPOINTS.md`](sync-kit/ts/TOUCHPOINTS.md) | Every TS/Capacitor touchpoint and `yadisk_*` settings key |
  169. | [`sync-kit/kotlin/TOUCHPOINTS.md`](sync-kit/kotlin/TOUCHPOINTS.md) | Every Kotlin/Android touchpoint and settings key |
  170. | [`skill/SKILL.md`](skill/SKILL.md) | The OpenCode skill itself |
  171. ## FAQ
  172. **Why WebDAV and not the Yandex Disk SDK?**
  173. No app registration, no OAuth keys, one file format, and it works identically from TypeScript and Kotlin.
  174. **Can I use it with another WebDAV provider?**
  175. The transport is standard WebDAV; only the default host and error wording are Yandex-specific.
  176. **Is live sync covered by tests?**
  177. No. XML parsing, naming, and the icon archive are unit-tested in the source apps; the live exchange is
  178. verified on a device (login, app password, Yandex 360).
  179. **Where are login and password stored?**
  180. In your app's settings store, and they are **excluded** from the cloud data file — verified by tests in
  181. the source projects.
  182. ## License
  183. MIT — see [LICENSE](LICENSE). Use it, ship it, adapt it.
  184. <p align="center">
  185. <a href="README.ru.md">Русский</a> · <a href="https://github.com/vladimirgorodok/yadisk-sync">GitHub</a>
  186. </p>
skill/scripts/install.mjs · Bundled script · 176 lines
  1. #!/usr/bin/env node
  2. /**
  3. * Раскладывает модуль обмена с Яндекс Диском из набора sync-kit в проект.
  4. *
  5. * Примеры:
  6. * node install.mjs --lang ts --project ~/work/my-app --dry-run
  7. * node install.mjs --lang ts --project ~/work/my-app --prefix moje-
  8. * node install.mjs --lang kotlin --project ~/work/my-app --package ru.myapp
  9. *
  10. * Что делает:
  11. * - копирует core без правок, project-example — переименовывая префикс файлов и package;
  12. * - никогда не перезаписывает существующие файлы без --force;
  13. * - ничего не патчит в исходниках проекта: стыки подключаются руками по TOUCHPOINTS.md;
  14. * - печатает, что осталось сделать вручную.
  15. */
  16. import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
  17. import { homedir } from 'node:os';
  18. import { dirname, join, resolve } from 'node:path';
  19. import { fileURLToPath } from 'node:url';
  20. const args = process.argv.slice(2);
  21. const opt = (name, fallback = '') => {
  22. const i = args.indexOf(`--${name}`);
  23. return i === -1 ? fallback : (args[i + 1] ?? '');
  24. };
  25. const flag = (name) => args.includes(`--${name}`);
  26. const lang = opt('lang');
  27. const project = opt('project');
  28. // Набор ищем так: явный --kit/SYNC_KIT, затем sync-kit рядом с навыком (автономный пакет),
  29. // затем привычное ~/workspace/sync-kit.
  30. const skillDir = resolve(dirname(fileURLToPath(import.meta.url)), '..');
  31. const bundledKit = join(skillDir, 'sync-kit');
  32. const homeKit = join(homedir(), 'workspace', 'sync-kit');
  33. const kit = resolve(
  34. opt('kit') ||
  35. process.env.SYNC_KIT ||
  36. (existsSync(bundledKit) ? bundledKit : homeKit),
  37. );
  38. const prefix = opt('prefix', lang === 'kotlin' ? 'platezhi2-' : 'avtobaza-');
  39. const pkg = opt('package');
  40. const dry = flag('dry-run');
  41. const force = flag('force');
  42. if (!['ts', 'kotlin'].includes(lang) || !project) {
  43. console.error('Использование: install.mjs --lang ts|kotlin --project <каталог> [--kit <каталог>]');
  44. console.error(' [--prefix имя-] [--package ru.проект] [--dry-run] [--force]');
  45. process.exit(2);
  46. }
  47. if (!existsSync(kit)) {
  48. console.error(`Не найден набор sync-kit: ${kit}\nУкажите --kit <каталог> или переменную SYNC_KIT.`);
  49. process.exit(2);
  50. }
  51. const root = resolve(project.replace(/^~/, homedir()));
  52. if (!existsSync(root)) {
  53. console.error(`Не найден проект: ${root}`);
  54. process.exit(2);
  55. }
  56. /** Замена в тексте: префикс имён файлов в облаке и package проекта */
  57. function rewrite(text) {
  58. const from = lang === 'kotlin' ? 'platezhi2' : 'avtobaza';
  59. let out = text;
  60. if (lang === 'kotlin') {
  61. if (!pkg) {
  62. console.error('Для Kotlin нужен --package, например --package ru.moje');
  63. process.exit(2);
  64. }
  65. out = out.split('ru.platezhi2.app').join(pkg);
  66. } else if (pkg) {
  67. // родной плагин: package и импорты должны совпасть с папкой проекта
  68. out = out.split('ru.avtobaza.app').join(pkg);
  69. }
  70. const base = prefix.replace(/-$/, '');
  71. if (base !== from) {
  72. out = out
  73. .split(`'${from}-icons-'`).join(`'${base}-icons-'`)
  74. .split(`'${from}-'`).join(`'${base}-'`)
  75. .split(`"${from}-icons-"`).join(`"${base}-icons-"`)
  76. .split(`"${from}-"`).join(`"${base}-"`)
  77. // папка на Диске по умолчанию и метка приложения в файле данных
  78. .split(`'/${from}'`).join(`'/${base}'`)
  79. .split(`"/${from}"`).join(`"/${base}"`)
  80. .split(`"${from}"`).join(`"${base}"`)
  81. .split(`'${from}'`).join(`'${base}'`);
  82. }
  83. return out;
  84. }
  85. const pkgPath = (pkg || 'ru.example.app').split('.').join('/');
  86. const files =
  87. lang === 'ts'
  88. ? [
  89. ['core/webdav.ts', 'src/lib/webdav.ts'],
  90. ['core/native-webdav.ts', 'src/lib/native-webdav.ts'],
  91. ['project-example/yadisk.ts', 'src/lib/yadisk.ts'],
  92. ['project-example/yadisk-auto.ts', 'src/lib/yadisk-auto.ts'],
  93. ['project-example/YandexDisk.tsx', 'src/pages/YandexDisk.tsx'],
  94. ...(pkg ? [['android/WebDavPlugin.java', `android/app/src/main/java/${pkgPath}/WebDavPlugin.java`]] : []),
  95. ]
  96. : [
  97. ['core/WebDavXml.kt', `app/src/main/java/${pkgPath}/data/cloud/WebDavXml.kt`],
  98. ['core/YandexDiskClient.kt', `app/src/main/java/${pkgPath}/data/cloud/YandexDiskClient.kt`],
  99. ['project-example/CloudSync.kt', `app/src/main/java/${pkgPath}/data/cloud/CloudSync.kt`],
  100. ['project-example/CloudSyncCoordinator.kt', `app/src/main/java/${pkgPath}/data/cloud/CloudSyncCoordinator.kt`],
  101. ['project-example/IconArchive.kt', `app/src/main/java/${pkgPath}/data/cloud/IconArchive.kt`],
  102. ];
  103. console.log(`Набор: ${kit}`);
  104. console.log(`Проект: ${root}`);
  105. console.log(`Стек: ${lang}${lang === 'kotlin' ? `, package ${pkg}` : ''}, префикс файлов в облаке: ${prefix}`);
  106. console.log(dry ? 'Режим: черновик, файлы не пишутся\n' : '\n');
  107. let created = 0;
  108. let skipped = 0;
  109. for (const [from, to] of files) {
  110. const src = join(kit, lang, from);
  111. const dst = join(root, to);
  112. if (!existsSync(src)) {
  113. console.log(` нет в наборе: ${from}`);
  114. continue;
  115. }
  116. if (existsSync(dst) && !force) {
  117. console.log(` пропуск (уже есть): ${to}`);
  118. skipped++;
  119. continue;
  120. }
  121. console.log(` ${existsSync(dst) ? 'замена' : 'новый'}: ${to}`);
  122. if (dry) continue;
  123. mkdirSync(dirname(dst), { recursive: true });
  124. writeFileSync(dst, rewrite(readFileSync(src, 'utf8')));
  125. created++;
  126. }
  127. if (!dry) console.log(`\nЗаписано файлов: ${created}, пропущено: ${skipped}`);
  128. // Функциональные имена переписаны, но упоминания в комментариях и текстах экрана остаются —
  129. // показываем их, чтобы ничего не забылось.
  130. if (!dry && created > 0) {
  131. const from = lang === 'kotlin' ? 'platezhi2' : 'avtobaza';
  132. const left = [];
  133. for (const [, to] of files) {
  134. const dst = join(root, to);
  135. if (!existsSync(dst)) continue;
  136. readFileSync(dst, 'utf8')
  137. .split('\n')
  138. .forEach((line, i) => {
  139. if (line.includes(from)) left.push(`${to}:${i + 1}: ${line.trim()}`);
  140. });
  141. }
  142. if (left.length > 0) {
  143. console.log(`\nУпоминания «${from}» в комментариях и текстах — поправьте по смыслу (${left.length}):`);
  144. for (const l of left.slice(0, 12)) console.log(` ${l}`);
  145. if (left.length > 12) console.log(` … и ещё ${left.length - 12}`);
  146. }
  147. }
  148. console.log(`
  149. Осталось сделать руками (см. ${lang}/TOUCHPOINTS.md в наборе):
  150. 1. Заменить стыки в скопированных файлах: сборка и применение данных, подсчёт записей,
  151. снимок перед заменой, архив значков и его разбор, хеш значков, сообщения об ошибках.
  152. 2. Добавить ключи настроек обмена (логин, пароль, папка, keep, auto, служебные last_*, dirty, last_error)
  153. так, чтобы они попадали в файл настроек проекта.
  154. 3. Подключить точки входа: экран обмена, пункт меню, автообмен (запуск, изменения, уход в фон).${
  155. lang === 'ts'
  156. ? `
  157. 4. Android: зарегистрировать WebDavPlugin в MainActivity.onCreate, добавить OkHttp в build.gradle,
  158. разрешение INTERNET в манифесте.${pkg ? '' : '\n (Файл плагина не скопирован — укажите --package ru.проект, чтобы разложить его в нужный пакет.)'}`
  159. : `
  160. 4. Android: разрешение INTERNET в манифесте, OkHttp в build.gradle, создание CloudSync
  161. и вызов автообмена там, где живёт состояние приложения.`
  162. }
  163. 5. Проверить по разделу 5 «Приёмка» в CHECKLIST.md.`);

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.