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.
Badge for your README
Markdown
[](/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
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
- <p align="center">
- <img src="assets/logo-256.png" width="128" height="128" alt="yadisk-sync logo">
- </p>
- <h1 align="center">yadisk-sync</h1>
- <p align="center">
- <b>App data ⇄ Yandex Disk over WebDAV.</b><br>
- A ready-to-drop reference module for <b>TypeScript/Capacitor</b> and <b>Kotlin/Android</b> apps —
- plus an <b>OpenCode skill</b> that wires it into your project for you.
- </p>
- <p align="center">
- <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>
- <img src="https://img.shields.io/badge/OpenCode-skill-111827.svg" alt="OpenCode skill">
- <img src="https://img.shields.io/badge/TypeScript-Capacitor-3178C6.svg?logo=typescript&logoColor=white" alt="TypeScript">
- <img src="https://img.shields.io/badge/Kotlin-Android-7F52FF.svg?logo=kotlin&logoColor=white" alt="Kotlin">
- <img src="https://img.shields.io/badge/WebDAV-Yandex%20Disk-FB5607.svg" alt="WebDAV">
- <img src="https://img.shields.io/badge/requires-Yandex%20360-FFCC00.svg" alt="Requires Yandex 360">
- </p>
- <p align="center">
- <b>English</b> · <a href="README.ru.md">Русский</a>
- </p>
- <p align="center">
- <img src="assets/social-preview.png" alt="yadisk-sync" width="820">
- </p>
- ---
- ## Why
- Cloud backup on Android is a swamp. OAuth providers want app registration and keys, sync APIs want SDKs,
- and "just upload a file" quietly turns into a week of plumbing — while one bad run can overwrite a user's
- only good copy with an empty database.
- `yadisk-sync` removes that week. It talks to **Yandex Disk over plain WebDAV**
- (`https://webdav.yandex.ru`) with an **app password** — no app registration, no OAuth keys — and ships
- the data-safety rules that stop a sync from destroying data.
- It is not a sketch. The reference code is a **byte-for-byte copy of two apps running in production**:
- - **Avtotracker** — TypeScript + Capacitor;
- - **Platezhi2** — Kotlin + native Android.
- ## What you get
- | | |
- |---|---|
- | 🔁 **Two implementations** | TypeScript/Capacitor and Kotlin/native Android, same protocol, same file format. |
- | 🧩 **Drop-in reference module** | `core` copies as-is; `project-example` is the integration you adapt, with every touchpoint documented. |
- | 🤖 **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. |
- | 🛡️ **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. |
- | 🖼️ **Icons as a separate archive** | The data file stays tiny; images ship as a ZIP only when they actually change (hash-compared). |
- | 📄 **Full protocol documentation** | Methods, XML parsing, failure codes, file naming, settings keys, and every project touchpoint. |
- ## Architecture
- The same exchange in both stacks:
- ```mermaid
- flowchart LR
- subgraph App["Your app"]
- UI["Sync screen<br/>(login, app password, folder, keep-N)"]
- DATA["Data layer<br/>tables + settings"]
- ICONS["Images / icons"]
- AUTO["Auto-sync<br/>on change · on launch · on background"]
- end
- subgraph Module["sync-kit module"]
- CORE["core<br/>WebDAV client, XML, errors"]
- PROJ["project-example<br/>push / pull / icons / safety"]
- end
- DISK[("Yandex Disk<br/>webdav.yandex.ru")]
- UI --> PROJ
- DATA --> PROJ
- ICONS --> PROJ
- AUTO --> PROJ
- PROJ --> CORE
- CORE -- "PROPFIND · MKCOL · PUT · GET · DELETE" --> DISK
- DISK -- "<prefix>-YYYY-MM-DD_HHmmss.json<br/><prefix>-icons-YYYY-MM-DD_HHmmss.zip" --> PROJ
- ```
- Two files land in your chosen folder on Disk:
- ```
- <prefix>-2026-11-20_143012.json data: every table + settings you cannot lose
- <prefix>-2026-11-20_143012.zip icons: images and document photos, only when changed
- ```
- ## Repository layout
- ```
- .
- ├── README.md ← you are here (English)
- ├── README.ru.md ← Русский
- ├── LICENSE ← MIT
- ├── assets/ ← logo, social preview
- ├── sync-kit/ ← the reference module (per-stack docs, core, project-example)
- │ ├── PROTOCOL.md ← how the exchange works: WebDAV, files, safety
- │ ├── CHECKLIST.md ← port it to a new project, step by step + acceptance list
- │ ├── ts/ ← TypeScript/Capacitor: core, project-example, native Android plugin
- │ └── kotlin/ ← Kotlin/native Android: core, project-example
- ├── skill/ ← OpenCode skill "yadisk-sync"
- │ ├── SKILL.md
- │ └── scripts/install.mjs ← lays the module files into a project
- ├── commands/sync-setup.md ← the /sync-setup command
- ├── packaging/ ← marketplace listing copy (Agensi)
- └── scripts/build-skill-package.mjs ← builds a self-contained skill .zip for marketplaces
- ```
- The code under `sync-kit/*/core` and `sync-kit/*/project-example` is a **byte-for-byte copy** of the
- production apps. It is never edited by hand — that is what keeps the reference trustworthy. Everything
- that is "project-specific" is listed in `sync-kit/ts/TOUCHPOINTS.md` and `sync-kit/kotlin/TOUCHPOINTS.md`.
- ## Quick start
- ### 1. Add the skill and command to OpenCode
- ```bash
- 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`):
- ```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`:
- ```jsonc
- { "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:
- ```bash
- 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):
- ```bash
- 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).
- ## Manual use (no agent)
- 1. Read `sync-kit/CHECKLIST.md` and tick off what your project already has (settings store, JSON
- export/import, image storage).
- 2. Copy `sync-kit/ts/core` or `sync-kit/kotlin/core` — **as is**.
- 3. Copy `project-example` and replace the project touchpoints using `TOUCHPOINTS.md`.
- 4. Verify: "Check connection", push, pull, empty-DB guard, background flush.
- ## Data-safety rules (the important part)
- These are not decoration — without them, sync corrupts data:
- 1. **An empty DB is never pushed over a non-empty one.** Local row count vs. cloud row count is
- compared first; upload stops with an explanation.
- 2. **A snapshot is taken before a "replace" restore.** Merge is the safe default; replace is not.
- 3. **The last N copies are kept** (default 5); older ones are deleted.
- 4. **Errors are quiet.** The message stays on the sync screen — no modal windows, no crashes.
- 5. **Your own uploads are not pulled back.** Push time and filename are remembered; the just-uploaded
- file is ignored during auto-sync (a ~10 s quiet window).
- ## Requirements
- - **Yandex app password**, not the account password. For WebDAV, create a password of type *Files*
- (or *WebDAV client*): <https://id.yandex.ru/security/app-passwords>.
- - **Yandex 360 subscription** — Disk is exposed over WebDAV to subscribers.
- - On Android, `PROPFIND` and `MKCOL` do **not** pass through the Capacitor HTTP bridge; the TypeScript
- stack ships a native OKHttp plugin (`sync-kit/ts/android/WebDavPlugin.java`).
- - Sync **cannot work in a browser** (Yandex CORS). The app must say so in words instead of failing silently.
- ## Documentation
- | Document | What it covers |
- |---|---|
- | [`sync-kit/PROTOCOL.md`](sync-kit/PROTOCOL.md) | WebDAV methods, XML parsing, error codes, file format, safety rules, auto-sync |
- | [`sync-kit/CHECKLIST.md`](sync-kit/CHECKLIST.md) | Porting order and the acceptance list |
- | [`sync-kit/ts/TOUCHPOINTS.md`](sync-kit/ts/TOUCHPOINTS.md) | Every TS/Capacitor touchpoint and `yadisk_*` settings key |
- | [`sync-kit/kotlin/TOUCHPOINTS.md`](sync-kit/kotlin/TOUCHPOINTS.md) | Every Kotlin/Android touchpoint and settings key |
- | [`skill/SKILL.md`](skill/SKILL.md) | The OpenCode skill itself |
- ## FAQ
- **Why WebDAV and not the Yandex Disk SDK?**
- No app registration, no OAuth keys, one file format, and it works identically from TypeScript and Kotlin.
- **Can I use it with another WebDAV provider?**
- The transport is standard WebDAV; only the default host and error wording are Yandex-specific.
- **Is live sync covered by tests?**
- No. XML parsing, naming, and the icon archive are unit-tested in the source apps; the live exchange is
- verified on a device (login, app password, Yandex 360).
- **Where are login and password stored?**
- In your app's settings store, and they are **excluded** from the cloud data file — verified by tests in
- the source projects.
- ## License
- MIT — see [LICENSE](LICENSE). Use it, ship it, adapt it.
- <p align="center">
- <a href="README.ru.md">Русский</a> · <a href="https://github.com/vladimirgorodok/yadisk-sync">GitHub</a>
- </p>
skill/scripts/install.mjs · Bundled script · 176 lines
- #!/usr/bin/env node
- /**
- * Раскладывает модуль обмена с Яндекс Диском из набора sync-kit в проект.
- *
- * Примеры:
- * node install.mjs --lang ts --project ~/work/my-app --dry-run
- * node install.mjs --lang ts --project ~/work/my-app --prefix moje-
- * node install.mjs --lang kotlin --project ~/work/my-app --package ru.myapp
- *
- * Что делает:
- * - копирует core без правок, project-example — переименовывая префикс файлов и package;
- * - никогда не перезаписывает существующие файлы без --force;
- * - ничего не патчит в исходниках проекта: стыки подключаются руками по TOUCHPOINTS.md;
- * - печатает, что осталось сделать вручную.
- */
- import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
- import { homedir } from 'node:os';
- import { dirname, join, resolve } from 'node:path';
- import { fileURLToPath } from 'node:url';
- const args = process.argv.slice(2);
- const opt = (name, fallback = '') => {
- const i = args.indexOf(`--${name}`);
- return i === -1 ? fallback : (args[i + 1] ?? '');
- };
- const flag = (name) => args.includes(`--${name}`);
- const lang = opt('lang');
- const project = opt('project');
- // Набор ищем так: явный --kit/SYNC_KIT, затем sync-kit рядом с навыком (автономный пакет),
- // затем привычное ~/workspace/sync-kit.
- const skillDir = resolve(dirname(fileURLToPath(import.meta.url)), '..');
- const bundledKit = join(skillDir, 'sync-kit');
- const homeKit = join(homedir(), 'workspace', 'sync-kit');
- const kit = resolve(
- opt('kit') ||
- process.env.SYNC_KIT ||
- (existsSync(bundledKit) ? bundledKit : homeKit),
- );
- const prefix = opt('prefix', lang === 'kotlin' ? 'platezhi2-' : 'avtobaza-');
- const pkg = opt('package');
- const dry = flag('dry-run');
- const force = flag('force');
- if (!['ts', 'kotlin'].includes(lang) || !project) {
- console.error('Использование: install.mjs --lang ts|kotlin --project <каталог> [--kit <каталог>]');
- console.error(' [--prefix имя-] [--package ru.проект] [--dry-run] [--force]');
- process.exit(2);
- }
- if (!existsSync(kit)) {
- console.error(`Не найден набор sync-kit: ${kit}\nУкажите --kit <каталог> или переменную SYNC_KIT.`);
- process.exit(2);
- }
- const root = resolve(project.replace(/^~/, homedir()));
- if (!existsSync(root)) {
- console.error(`Не найден проект: ${root}`);
- process.exit(2);
- }
- /** Замена в тексте: префикс имён файлов в облаке и package проекта */
- function rewrite(text) {
- const from = lang === 'kotlin' ? 'platezhi2' : 'avtobaza';
- let out = text;
- if (lang === 'kotlin') {
- if (!pkg) {
- console.error('Для Kotlin нужен --package, например --package ru.moje');
- process.exit(2);
- }
- out = out.split('ru.platezhi2.app').join(pkg);
- } else if (pkg) {
- // родной плагин: package и импорты должны совпасть с папкой проекта
- out = out.split('ru.avtobaza.app').join(pkg);
- }
- const base = prefix.replace(/-$/, '');
- if (base !== from) {
- out = out
- .split(`'${from}-icons-'`).join(`'${base}-icons-'`)
- .split(`'${from}-'`).join(`'${base}-'`)
- .split(`"${from}-icons-"`).join(`"${base}-icons-"`)
- .split(`"${from}-"`).join(`"${base}-"`)
- // папка на Диске по умолчанию и метка приложения в файле данных
- .split(`'/${from}'`).join(`'/${base}'`)
- .split(`"/${from}"`).join(`"/${base}"`)
- .split(`"${from}"`).join(`"${base}"`)
- .split(`'${from}'`).join(`'${base}'`);
- }
- return out;
- }
- const pkgPath = (pkg || 'ru.example.app').split('.').join('/');
- const files =
- lang === 'ts'
- ? [
- ['core/webdav.ts', 'src/lib/webdav.ts'],
- ['core/native-webdav.ts', 'src/lib/native-webdav.ts'],
- ['project-example/yadisk.ts', 'src/lib/yadisk.ts'],
- ['project-example/yadisk-auto.ts', 'src/lib/yadisk-auto.ts'],
- ['project-example/YandexDisk.tsx', 'src/pages/YandexDisk.tsx'],
- ...(pkg ? [['android/WebDavPlugin.java', `android/app/src/main/java/${pkgPath}/WebDavPlugin.java`]] : []),
- ]
- : [
- ['core/WebDavXml.kt', `app/src/main/java/${pkgPath}/data/cloud/WebDavXml.kt`],
- ['core/YandexDiskClient.kt', `app/src/main/java/${pkgPath}/data/cloud/YandexDiskClient.kt`],
- ['project-example/CloudSync.kt', `app/src/main/java/${pkgPath}/data/cloud/CloudSync.kt`],
- ['project-example/CloudSyncCoordinator.kt', `app/src/main/java/${pkgPath}/data/cloud/CloudSyncCoordinator.kt`],
- ['project-example/IconArchive.kt', `app/src/main/java/${pkgPath}/data/cloud/IconArchive.kt`],
- ];
- console.log(`Набор: ${kit}`);
- console.log(`Проект: ${root}`);
- console.log(`Стек: ${lang}${lang === 'kotlin' ? `, package ${pkg}` : ''}, префикс файлов в облаке: ${prefix}`);
- console.log(dry ? 'Режим: черновик, файлы не пишутся\n' : '\n');
- let created = 0;
- let skipped = 0;
- for (const [from, to] of files) {
- const src = join(kit, lang, from);
- const dst = join(root, to);
- if (!existsSync(src)) {
- console.log(` нет в наборе: ${from}`);
- continue;
- }
- if (existsSync(dst) && !force) {
- console.log(` пропуск (уже есть): ${to}`);
- skipped++;
- continue;
- }
- console.log(` ${existsSync(dst) ? 'замена' : 'новый'}: ${to}`);
- if (dry) continue;
- mkdirSync(dirname(dst), { recursive: true });
- writeFileSync(dst, rewrite(readFileSync(src, 'utf8')));
- created++;
- }
- if (!dry) console.log(`\nЗаписано файлов: ${created}, пропущено: ${skipped}`);
- // Функциональные имена переписаны, но упоминания в комментариях и текстах экрана остаются —
- // показываем их, чтобы ничего не забылось.
- if (!dry && created > 0) {
- const from = lang === 'kotlin' ? 'platezhi2' : 'avtobaza';
- const left = [];
- for (const [, to] of files) {
- const dst = join(root, to);
- if (!existsSync(dst)) continue;
- readFileSync(dst, 'utf8')
- .split('\n')
- .forEach((line, i) => {
- if (line.includes(from)) left.push(`${to}:${i + 1}: ${line.trim()}`);
- });
- }
- if (left.length > 0) {
- console.log(`\nУпоминания «${from}» в комментариях и текстах — поправьте по смыслу (${left.length}):`);
- for (const l of left.slice(0, 12)) console.log(` ${l}`);
- if (left.length > 12) console.log(` … и ещё ${left.length - 12}`);
- }
- }
- console.log(`
- Осталось сделать руками (см. ${lang}/TOUCHPOINTS.md в наборе):
- 1. Заменить стыки в скопированных файлах: сборка и применение данных, подсчёт записей,
- снимок перед заменой, архив значков и его разбор, хеш значков, сообщения об ошибках.
- 2. Добавить ключи настроек обмена (логин, пароль, папка, keep, auto, служебные last_*, dirty, last_error)
- так, чтобы они попадали в файл настроек проекта.
- 3. Подключить точки входа: экран обмена, пункт меню, автообмен (запуск, изменения, уход в фон).${
- lang === 'ts'
- ? `
- 4. Android: зарегистрировать WebDavPlugin в MainActivity.onCreate, добавить OkHttp в build.gradle,
- разрешение INTERNET в манифесте.${pkg ? '' : '\n (Файл плагина не скопирован — укажите --package ru.проект, чтобы разложить его в нужный пакет.)'}`
- : `
- 4. Android: разрешение INTERNET в манифесте, OkHttp в build.gradle, создание CloudSync
- и вызов автообмена там, где живёт состояние приложения.`
- }
- 5. Проверить по разделу 5 «Приёмка» в CHECKLIST.md.`);
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.