shared-hosting-sync 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (46) hide show
  1. package/.env.example +23 -0
  2. package/CHANGELOG.md +24 -0
  3. package/LICENSE +21 -0
  4. package/PHASES.md +147 -0
  5. package/PRODUCT.md +90 -0
  6. package/README.md +398 -2
  7. package/RELEASING.md +79 -0
  8. package/package.json +68 -4
  9. package/src/arguments.js +30 -0
  10. package/src/bin.js +8 -0
  11. package/src/checksum.js +18 -0
  12. package/src/cli.js +511 -0
  13. package/src/config.js +98 -0
  14. package/src/core/db.js +61 -0
  15. package/src/core/deployment.js +22 -0
  16. package/src/core/envResolver.js +98 -0
  17. package/src/core/envSchema.js +160 -0
  18. package/src/core/migrate.js +75 -0
  19. package/src/core/migrations/001_init.sql +67 -0
  20. package/src/core/migrations/002_operation_locks.sql +9 -0
  21. package/src/core/operationLock.js +54 -0
  22. package/src/core/projects.js +261 -0
  23. package/src/core/secrets.js +75 -0
  24. package/src/core/v1Migrate.js +82 -0
  25. package/src/ignore.js +148 -0
  26. package/src/metadata.js +3 -0
  27. package/src/onboarding.js +117 -0
  28. package/src/paths.js +23 -0
  29. package/src/prompt.js +54 -0
  30. package/src/server/browse.js +46 -0
  31. package/src/server/deployments.js +209 -0
  32. package/src/server/index.js +79 -0
  33. package/src/server/local.js +23 -0
  34. package/src/server/onboarding.js +203 -0
  35. package/src/server/routes.js +307 -0
  36. package/src/server/session.js +58 -0
  37. package/src/transport/ftp.js +100 -0
  38. package/src/transport/index.js +12 -0
  39. package/src/transport/reliable.js +50 -0
  40. package/src/transport/sftp.js +99 -0
  41. package/src/ui/deployments.js +129 -0
  42. package/src/ui/index.html +17 -0
  43. package/src/ui/style.css +129 -0
  44. package/src/ui/ui.js +289 -0
  45. package/src/uploader.js +160 -0
  46. package/src/watcher.js +122 -0
@@ -0,0 +1,98 @@
1
+ // Resolve only documented devsync settings; application secrets stay untouched.
2
+ import fs from 'node:fs'
3
+ import path from 'node:path'
4
+ import os from 'node:os'
5
+ import dotenv from 'dotenv'
6
+ import { ENV_SCHEMA, defaultsFor, validate } from './envSchema.js'
7
+ import { effectiveEnv, getProject } from './projects.js'
8
+ import { validateRemotePath } from '../paths.js'
9
+
10
+ const recognized = new Set(ENV_SCHEMA.map((s) => s.key))
11
+ const present = (value) => value !== undefined && value !== null && value !== ''
12
+
13
+ export function resolveEnv(projectId, { transport = 'sftp', envFile, localPath, overrides = {}, useEnvFileEnvironment = true } = {}) {
14
+ const project = projectId == null ? null : getProject(projectId)
15
+ localPath = localPath || project?.localPath
16
+ if (!localPath) throw new Error('A local project folder is required')
17
+ const values = { ...defaultsFor(transport) }
18
+ const sources = Object.fromEntries(ENV_SCHEMA.map((s) => [s.key, 'default']))
19
+ if (project) {
20
+ const saved = effectiveEnv(projectId, transport)
21
+ for (const [key, value] of Object.entries(saved.values)) {
22
+ if (recognized.has(key) && present(value)) {
23
+ values[key] = value
24
+ sources[key] = saved.sources[key]
25
+ }
26
+ }
27
+ }
28
+ const explicitFile = envFile || (useEnvFileEnvironment ? process.env.DEVSYNC_ENV_FILE : undefined)
29
+ if (explicitFile && typeof explicitFile !== 'string') throw new Error('--env-file requires a file path')
30
+ const layers = explicitFile
31
+ ? [{ file: path.resolve(explicitFile), source: envFile ? '--env-file' : 'DEVSYNC_ENV_FILE', required: true }]
32
+ : ['.devsync.env', '.env'].map((name) => ({ file: path.join(localPath, name), source: name }))
33
+ for (const layer of layers) {
34
+ if (!fs.existsSync(layer.file)) {
35
+ if (layer.required) throw new Error('The selected environment file does not exist')
36
+ continue
37
+ }
38
+ const relative = path.relative(localPath, layer.file)
39
+ const name = path.basename(layer.file)
40
+ const insideProject = !path.isAbsolute(relative) && relative !== '..' && !relative.startsWith('..' + path.sep)
41
+ if (insideProject && name !== '.env' && !name.startsWith('.env.') && name !== '.devsync.env') {
42
+ throw new Error('An environment file inside the project must be named .env, .env.*, or .devsync.env so it stays excluded from deployment')
43
+ }
44
+ const parsed = dotenv.parse(fs.readFileSync(layer.file, 'utf8'))
45
+ for (const [key, value] of Object.entries(parsed)) {
46
+ if (recognized.has(key) && present(value)) {
47
+ values[key] = value
48
+ sources[key] = layer.source
49
+ }
50
+ }
51
+ }
52
+ for (const [key, value] of Object.entries(overrides)) {
53
+ if (recognized.has(key) && present(value)) {
54
+ values[key] = value
55
+ sources[key] = 'cli'
56
+ }
57
+ }
58
+ if (sources.DEVSYNC_PORT === 'default') values.DEVSYNC_PORT = defaultsFor(values.DEVSYNC_TRANSPORT).DEVSYNC_PORT
59
+ if (values.DEVSYNC_PRIVATE_KEY) {
60
+ const keyPath = values.DEVSYNC_PRIVATE_KEY
61
+ values.DEVSYNC_PRIVATE_KEY = keyPath.startsWith('~/') || keyPath.startsWith('~\\')
62
+ ? path.join(os.homedir(), keyPath.slice(2)) : path.resolve(localPath, keyPath)
63
+ }
64
+ const warnings = ENV_SCHEMA.map((s) => settingError(s.key, values[s.key], values)).filter(Boolean)
65
+ return { values, sources, warnings }
66
+ }
67
+
68
+ export function settingError(key, value, values = {}) {
69
+ if (key === 'DEVSYNC_PASSWORD' && values.DEVSYNC_TRANSPORT === 'sftp' && values.DEVSYNC_PRIVATE_KEY && !value) return null
70
+ const result = validate(key, value)
71
+ if (!result.ok) return result.message
72
+ if (key === 'DEVSYNC_HOST' && value && (/\s|\/|\\/.test(value))) return 'DEVSYNC_HOST must be a hostname or IP without a URL scheme'
73
+ if (key === 'DEVSYNC_USERNAME' && value && !String(value).trim()) return 'DEVSYNC_USERNAME is required'
74
+ if (key === 'DEVSYNC_REMOTE_PATH') {
75
+ try { validateRemotePath(value) } catch (err) { return err.message }
76
+ }
77
+ if (key === 'DEVSYNC_PRIVATE_KEY' && value && values.DEVSYNC_TRANSPORT === 'sftp') {
78
+ try {
79
+ if (!fs.statSync(value).isFile()) return 'DEVSYNC_PRIVATE_KEY must point to a file'
80
+ fs.accessSync(value, fs.constants.R_OK)
81
+ } catch { return 'DEVSYNC_PRIVATE_KEY must point to a readable local file' }
82
+ }
83
+ return null
84
+ }
85
+
86
+ export function credsFromResolved(values) {
87
+ const transport = values.DEVSYNC_TRANSPORT
88
+ return {
89
+ transport,
90
+ host: values.DEVSYNC_HOST,
91
+ port: Number(values.DEVSYNC_PORT || (transport === 'sftp' ? 22 : 21)),
92
+ username: values.DEVSYNC_USERNAME,
93
+ password: values.DEVSYNC_PASSWORD || undefined,
94
+ privateKeyPath: transport === 'sftp' ? values.DEVSYNC_PRIVATE_KEY || undefined : undefined,
95
+ secure: transport === 'ftps',
96
+ timeoutMs: 20000
97
+ }
98
+ }
@@ -0,0 +1,160 @@
1
+ // ENV_SCHEMA — the single source of truth for every DEVSYNC_* variable.
2
+ // The CLI validator, the UI form, and the docs are all generated from this.
3
+ //
4
+ // Conventions:
5
+ // - type: 'string' | 'int' | 'bool' | 'enum' | 'path' | 'secret'
6
+ // - required: true|false
7
+ // - default: literal value
8
+ // - values: array of allowed values (for enum)
9
+ // - min/max: range (for int)
10
+ // - secret: true|false — never logged, masked in UI
11
+ // - help: one-line explanation shown in the UI
12
+ // - label: human label shown in the UI
13
+ //
14
+ // Adding a new variable? Add it here, and the UI form picks it up.
15
+
16
+ export const ENV_SCHEMA = [
17
+ {
18
+ key: 'DEVSYNC_TRANSPORT',
19
+ type: 'enum',
20
+ values: ['sftp', 'ftp', 'ftps'],
21
+ default: 'sftp',
22
+ required: true,
23
+ label: 'Protocol',
24
+ help: 'sftp is encrypted and supports parallel transfers; ftps is encrypted FTP; ftp is plaintext (avoid)'
25
+ },
26
+ {
27
+ key: 'DEVSYNC_HOST',
28
+ type: 'string',
29
+ required: true,
30
+ label: 'Host',
31
+ help: 'Hostname or IP. For Hostinger SFTP use the host shown in your panel.'
32
+ },
33
+ {
34
+ key: 'DEVSYNC_PORT',
35
+ type: 'int',
36
+ defaultBy: 'transport', // 22 for sftp, 21 for ftp/ftps — see DEFAULTS_BY_TRANSPORT
37
+ required: false,
38
+ min: 1,
39
+ max: 65535,
40
+ label: 'Port',
41
+ help: 'Leave blank to use the protocol default (22 for sftp, 21 for ftp/ftps).'
42
+ },
43
+ {
44
+ key: 'DEVSYNC_USERNAME',
45
+ type: 'string',
46
+ required: true,
47
+ label: 'Username',
48
+ help: 'Your hosting account username.'
49
+ },
50
+ {
51
+ key: 'DEVSYNC_PASSWORD',
52
+ type: 'secret',
53
+ required: true,
54
+ label: 'Password',
55
+ help: 'Or the passphrase for DEVSYNC_PRIVATE_KEY. Stored encrypted with AES-256-GCM.'
56
+ },
57
+ {
58
+ key: 'DEVSYNC_PRIVATE_KEY',
59
+ type: 'path',
60
+ required: false,
61
+ label: 'SSH private key (optional)',
62
+ help: 'Path to an SSH key. SFTP only. Use instead of a password for stronger auth.'
63
+ },
64
+ {
65
+ key: 'DEVSYNC_REMOTE_PATH',
66
+ type: 'path',
67
+ required: true,
68
+ label: 'Remote path',
69
+ help: 'The folder on the server you sync to. Use Browse in the UI to find it.'
70
+ },
71
+ {
72
+ key: 'DEVSYNC_IGNORE_DELETES',
73
+ type: 'bool',
74
+ default: true,
75
+ label: 'Never mirror deletes (one-way push)',
76
+ help: 'Local deletes stay local. Recommended for shared hosting.'
77
+ },
78
+ {
79
+ key: 'DEVSYNC_DRY_RUN',
80
+ type: 'bool',
81
+ default: false,
82
+ label: 'Dry run',
83
+ help: 'Plan and report without uploading.'
84
+ },
85
+ {
86
+ key: 'DEVSYNC_DEBOUNCE_MS',
87
+ type: 'int',
88
+ default: 400,
89
+ min: 100,
90
+ max: 10000,
91
+ label: 'Watcher debounce (ms)',
92
+ help: 'How long to wait after a file change before uploading.'
93
+ }
94
+ ]
95
+
96
+ export const DEFAULTS_BY_TRANSPORT = {
97
+ sftp: 22,
98
+ ftp: 21,
99
+ ftps: 21
100
+ }
101
+
102
+ const BY_KEY = new Map(ENV_SCHEMA.map((s) => [s.key, s]))
103
+
104
+ /** Get a schema entry by key. Throws if the key is unknown — that's a programmer error. */
105
+ export function get(key) {
106
+ const s = BY_KEY.get(key)
107
+ if (!s) throw new Error(`unknown envSchema key: ${key}`)
108
+ return s
109
+ }
110
+
111
+ /** Build a default value map, applying transport-aware defaults. */
112
+ export function defaultsFor(transport) {
113
+ const out = {}
114
+ for (const s of ENV_SCHEMA) {
115
+ if (s.default !== undefined) {
116
+ out[s.key] = s.default
117
+ } else if (s.defaultBy === 'transport' && s.key === 'DEVSYNC_PORT') {
118
+ out[s.key] = DEFAULTS_BY_TRANSPORT[transport] ?? null
119
+ }
120
+ }
121
+ return out
122
+ }
123
+
124
+ /** Validate a key/value against its schema entry. Returns { ok, message }. */
125
+ export function validate(key, value) {
126
+ const s = BY_KEY.get(key)
127
+ if (!s) {
128
+ return { ok: false, message: `unknown key: ${key}` }
129
+ }
130
+ if ((value === '' || value == null) && s.required) {
131
+ return { ok: false, message: `${key} is required` }
132
+ }
133
+ if (value === '' || value == null) {
134
+ return { ok: true }
135
+ }
136
+ switch (s.type) {
137
+ case 'int': {
138
+ const n = Number(value)
139
+ if (!Number.isInteger(n)) return { ok: false, message: `${key} must be an integer` }
140
+ if (s.min != null && n < s.min) return { ok: false, message: `${key} must be >= ${s.min}` }
141
+ if (s.max != null && n > s.max) return { ok: false, message: `${key} must be <= ${s.max}` }
142
+ return { ok: true }
143
+ }
144
+ case 'bool':
145
+ if (value === true || value === false) return { ok: true }
146
+ if (value === 'true' || value === 'false' || value === '1' || value === '0') return { ok: true }
147
+ return { ok: false, message: `${key} must be true or false` }
148
+ case 'enum': {
149
+ if (!s.values.includes(value)) {
150
+ return { ok: false, message: `${key} must be one of: ${s.values.join(', ')}` }
151
+ }
152
+ return { ok: true }
153
+ }
154
+ case 'string':
155
+ case 'path':
156
+ case 'secret':
157
+ return { ok: true }
158
+ }
159
+ return { ok: true }
160
+ }
@@ -0,0 +1,75 @@
1
+ // migrate.js — runs SQL files from ./migrations in order.
2
+ //
3
+ // Files are named NNN_anything.sql (e.g. 001_init.sql). The applied version
4
+ // is stored in schema_meta. On open, we read the current version, then
5
+ // apply every file whose NNN is greater, in numeric order. Each migration
6
+ // runs inside a transaction.
7
+ //
8
+ // Idempotency: migrations should be safe to re-run with IF NOT EXISTS so a
9
+ // crashed-run mid-migration can't leave the DB half-upgraded. The version
10
+ // row is the source of truth — we only bump it after the tx commits.
11
+
12
+ import fs from 'node:fs'
13
+ import path from 'node:path'
14
+ import { fileURLToPath } from 'node:url'
15
+
16
+ const HERE = path.dirname(fileURLToPath(import.meta.url))
17
+ const MIGRATIONS_DIR = path.join(HERE, 'migrations')
18
+
19
+ function listMigrations() {
20
+ if (!fs.existsSync(MIGRATIONS_DIR)) return []
21
+ return fs
22
+ .readdirSync(MIGRATIONS_DIR)
23
+ .filter((f) => f.endsWith('.sql'))
24
+ .sort() // alphabetical = numeric for "001_", "002_", …
25
+ .map((f) => {
26
+ const m = f.match(/^(\d+)_/)
27
+ if (!m) throw new Error(`migration file must start with NNN_: ${f}`)
28
+ return { file: f, version: Number(m[1]) }
29
+ })
30
+ }
31
+
32
+ function currentVersion(db) {
33
+ // schema_meta may not exist yet — brand-new DB starts at version 0.
34
+ const row = db
35
+ .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='schema_meta'")
36
+ .get()
37
+ if (!row) return 0
38
+ const r = db.prepare("SELECT value FROM schema_meta WHERE key='version'").get()
39
+ return r ? Number(r.value) : 0
40
+ }
41
+
42
+ function setVersion(db, version) {
43
+ // Two cases:
44
+ // - schema_meta table doesn't exist yet (this is the 001 migration
45
+ // itself) — 001's SQL creates it and inserts ('version','1').
46
+ // - schema_meta exists — UPSERT.
47
+ const hasTable = db
48
+ .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='schema_meta'")
49
+ .get()
50
+ if (hasTable) {
51
+ db.prepare("INSERT INTO schema_meta (key, value) VALUES ('version', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value").run(
52
+ String(version)
53
+ )
54
+ }
55
+ }
56
+
57
+ export function runMigrations(db) {
58
+ const all = listMigrations()
59
+ let version = currentVersion(db)
60
+ const pending = all.filter((m) => m.version > version)
61
+ for (const m of pending) {
62
+ const sql = fs.readFileSync(path.join(MIGRATIONS_DIR, m.file), 'utf8')
63
+ db.exec('BEGIN')
64
+ try {
65
+ db.exec(sql)
66
+ setVersion(db, m.version)
67
+ db.exec('COMMIT')
68
+ } catch (e) {
69
+ try { db.exec('ROLLBACK') } catch {}
70
+ throw new Error(`migration ${m.file} failed: ${e.message}`)
71
+ }
72
+ version = m.version
73
+ }
74
+ return { applied: pending.map((m) => m.file), version }
75
+ }
@@ -0,0 +1,67 @@
1
+ -- 001_init.sql — initial devsync v2 schema.
2
+ -- Mirrors DB-SCHEMA.md §"The proposed schema" (5 tables, 4 indexes).
3
+
4
+ CREATE TABLE schema_meta (
5
+ key TEXT PRIMARY KEY,
6
+ value TEXT NOT NULL
7
+ );
8
+
9
+ CREATE TABLE projects (
10
+ id INTEGER PRIMARY KEY,
11
+ label TEXT NOT NULL UNIQUE,
12
+ local_path TEXT NOT NULL UNIQUE, -- canonical realpath
13
+ enabled INTEGER NOT NULL DEFAULT 1,
14
+ created_at TEXT NOT NULL, -- ISO 8601 UTC
15
+ updated_at TEXT NOT NULL,
16
+
17
+ last_status TEXT NOT NULL DEFAULT 'idle', -- idle|planning|syncing|watching|error
18
+ last_error TEXT,
19
+ last_sync_at TEXT,
20
+ last_upload_bytes INTEGER,
21
+
22
+ probe_shell INTEGER, -- capability probes; NULL = not probed
23
+ probe_tar INTEGER,
24
+ probe_unzip INTEGER,
25
+ probe_at TEXT
26
+ );
27
+
28
+ CREATE INDEX idx_projects_enabled ON projects(enabled);
29
+
30
+ -- Encrypted creds for a project (one row, one cipher blob).
31
+ CREATE TABLE secrets (
32
+ project_id INTEGER PRIMARY KEY REFERENCES projects(id) ON DELETE CASCADE,
33
+ ciphertext TEXT NOT NULL, -- base64 AES-256-GCM
34
+ iv TEXT NOT NULL, -- base64 12-byte IV
35
+ auth_tag TEXT NOT NULL, -- base64 16-byte GCM tag
36
+ updated_at TEXT NOT NULL
37
+ );
38
+
39
+ -- Per-key env overrides. value is NULL when is_secret=1 (the secret is in
40
+ -- the secrets table, not here).
41
+ CREATE TABLE env_overrides (
42
+ project_id INTEGER NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
43
+ key TEXT NOT NULL,
44
+ value TEXT,
45
+ is_secret INTEGER NOT NULL DEFAULT 0,
46
+ updated_at TEXT NOT NULL,
47
+ PRIMARY KEY (project_id, key)
48
+ );
49
+
50
+ -- Events: status transitions, uploads, errors, transport, etc.
51
+ CREATE TABLE events (
52
+ id INTEGER PRIMARY KEY,
53
+ project_id INTEGER NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
54
+ ts TEXT NOT NULL, -- ISO 8601 UTC
55
+ level TEXT NOT NULL, -- debug|info|warn|error
56
+ kind TEXT NOT NULL, -- status|upload|watch|config|transport|system
57
+ message TEXT NOT NULL,
58
+ file TEXT,
59
+ bytes INTEGER,
60
+ duration_ms INTEGER,
61
+ error_code TEXT
62
+ );
63
+
64
+ CREATE INDEX idx_events_project_ts ON events(project_id, ts DESC);
65
+ CREATE INDEX idx_events_kind ON events(project_id, kind, ts DESC);
66
+
67
+ INSERT INTO schema_meta (key, value) VALUES ('version', '1');
@@ -0,0 +1,9 @@
1
+ CREATE TABLE IF NOT EXISTS operation_locks (
2
+ token TEXT PRIMARY KEY,
3
+ project_id INTEGER NOT NULL,
4
+ pid INTEGER NOT NULL,
5
+ kind TEXT NOT NULL,
6
+ endpoint TEXT,
7
+ remote_path TEXT,
8
+ started_at TEXT NOT NULL
9
+ );
@@ -0,0 +1,54 @@
1
+ import crypto from 'node:crypto'
2
+ import { openDb } from './db.js'
3
+
4
+ function alive(pid) {
5
+ try { process.kill(pid, 0); return true }
6
+ catch (error) { return error.code !== 'ESRCH' }
7
+ }
8
+
9
+ function rows(db) {
10
+ const locks = db.prepare('SELECT * FROM operation_locks').all()
11
+ for (const lock of locks) {
12
+ if (!alive(lock.pid)) db.prepare('DELETE FROM operation_locks WHERE token = ?').run(lock.token)
13
+ }
14
+ return locks.filter((lock) => alive(lock.pid))
15
+ }
16
+
17
+ const overlaps = (a, b) => a === '/' || b === '/' || a === b || a.startsWith(b + '/') || b.startsWith(a + '/')
18
+ const conflict = () => Object.assign(new Error('This project or server destination has an operation running in another CLI or dashboard. Stop watching or wait for it to finish.'), { statusCode: 409 })
19
+
20
+ /** Local-machine coordination for processes sharing DEVSYNC_HOME. No credentials stored. */
21
+ export function acquireOperation(projectId, kind, { creds, remotePath } = {}) {
22
+ const db = openDb()
23
+ const endpoint = creds ? crypto.createHash('sha256').update(JSON.stringify([
24
+ creds.transport, String(creds.host).toLowerCase(), Number(creds.port), creds.username
25
+ ])).digest('hex') : null
26
+ const token = crypto.randomUUID()
27
+ db.exec('BEGIN IMMEDIATE')
28
+ try {
29
+ if (rows(db).some((lock) => lock.project_id === projectId || endpoint && lock.endpoint === endpoint && overlaps(remotePath, lock.remote_path))) throw conflict()
30
+ db.prepare('INSERT INTO operation_locks (token, project_id, pid, kind, endpoint, remote_path, started_at) VALUES (?, ?, ?, ?, ?, ?, ?)')
31
+ .run(token, projectId, process.pid, kind, endpoint, remotePath || null, new Date().toISOString())
32
+ db.exec('COMMIT')
33
+ } catch (error) { db.exec('ROLLBACK'); throw error }
34
+ let released = false
35
+ return () => {
36
+ if (released) return
37
+ db.prepare('DELETE FROM operation_locks WHERE token = ?').run(token)
38
+ released = true
39
+ }
40
+ }
41
+
42
+ export function assertProjectIdle(projectId) {
43
+ if (rows(openDb()).some((lock) => lock.project_id === Number(projectId))) throw conflict()
44
+ }
45
+
46
+ export function mutateProject(projectId, action) {
47
+ const release = acquireOperation(Number(projectId), 'settings')
48
+ try { return action() } finally { release() }
49
+ }
50
+
51
+ export function projectOperation(projectId) {
52
+ const lock = rows(openDb()).find((row) => row.project_id === Number(projectId))
53
+ return lock ? { kind: lock.kind, startedAt: lock.started_at } : null
54
+ }