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.
- package/.env.example +23 -0
- package/CHANGELOG.md +24 -0
- package/LICENSE +21 -0
- package/PHASES.md +147 -0
- package/PRODUCT.md +90 -0
- package/README.md +398 -2
- package/RELEASING.md +79 -0
- package/package.json +68 -4
- package/src/arguments.js +30 -0
- package/src/bin.js +8 -0
- package/src/checksum.js +18 -0
- package/src/cli.js +511 -0
- package/src/config.js +98 -0
- package/src/core/db.js +61 -0
- package/src/core/deployment.js +22 -0
- package/src/core/envResolver.js +98 -0
- package/src/core/envSchema.js +160 -0
- package/src/core/migrate.js +75 -0
- package/src/core/migrations/001_init.sql +67 -0
- package/src/core/migrations/002_operation_locks.sql +9 -0
- package/src/core/operationLock.js +54 -0
- package/src/core/projects.js +261 -0
- package/src/core/secrets.js +75 -0
- package/src/core/v1Migrate.js +82 -0
- package/src/ignore.js +148 -0
- package/src/metadata.js +3 -0
- package/src/onboarding.js +117 -0
- package/src/paths.js +23 -0
- package/src/prompt.js +54 -0
- package/src/server/browse.js +46 -0
- package/src/server/deployments.js +209 -0
- package/src/server/index.js +79 -0
- package/src/server/local.js +23 -0
- package/src/server/onboarding.js +203 -0
- package/src/server/routes.js +307 -0
- package/src/server/session.js +58 -0
- package/src/transport/ftp.js +100 -0
- package/src/transport/index.js +12 -0
- package/src/transport/reliable.js +50 -0
- package/src/transport/sftp.js +99 -0
- package/src/ui/deployments.js +129 -0
- package/src/ui/index.html +17 -0
- package/src/ui/style.css +129 -0
- package/src/ui/ui.js +289 -0
- package/src/uploader.js +160 -0
- package/src/watcher.js +122 -0
package/README.md
CHANGED
|
@@ -1,3 +1,399 @@
|
|
|
1
|
-
#
|
|
1
|
+
# shared-hosting-sync
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Deploy local projects to shared hosting through FTP, FTPS, or SFTP. Install once,
|
|
4
|
+
choose a local folder and a server destination, then deploy or keep files in sync.
|
|
5
|
+
|
|
6
|
+
Use the terminal or a local browser dashboard. Both interfaces control the same
|
|
7
|
+
projects, settings, and deployment operations.
|
|
8
|
+
|
|
9
|
+
> **Version 0.1.0:** Requires Node.js 24 or newer.
|
|
10
|
+
> CLI and UI onboarding, previews, deployment, sync, and watching are implemented.
|
|
11
|
+
|
|
12
|
+
The package name is **shared-hosting-sync**. Run it as `shared-hosting-sync` or
|
|
13
|
+
use the shorter `devsync` alias shown in examples below. Both commands run the
|
|
14
|
+
same application. Existing `DEVSYNC_*` variables and `~/.devsync/` settings stay
|
|
15
|
+
compatible with development versions.
|
|
16
|
+
|
|
17
|
+
## Why shared-hosting-sync?
|
|
18
|
+
|
|
19
|
+
Many shared hosting accounts accept file uploads without offering a deployment
|
|
20
|
+
pipeline. devsync connects your development machine to that hosting account.
|
|
21
|
+
Your source can live in GitHub or any other repository; devsync deploys the files
|
|
22
|
+
on your machine without requiring Git or a deployment agent on the server.
|
|
23
|
+
|
|
24
|
+
- Install globally, outside the projects you deploy.
|
|
25
|
+
- Save multiple projects with separate hosting details and destinations.
|
|
26
|
+
- Preview uploads before changing server files.
|
|
27
|
+
- Deploy once, sync changed files, or watch local changes.
|
|
28
|
+
- Exclude local dependencies, secrets, and development files.
|
|
29
|
+
|
|
30
|
+
The host must support the application you upload. Static build output and PHP
|
|
31
|
+
files work with suitable shared hosting; server applications still need their
|
|
32
|
+
runtime supported by the hosting provider.
|
|
33
|
+
|
|
34
|
+
## Installation
|
|
35
|
+
|
|
36
|
+
Requires **Node.js 24 or newer** and npm. Hosting credentials and access to the
|
|
37
|
+
destination folder are also required.
|
|
38
|
+
|
|
39
|
+
Install globally:
|
|
40
|
+
|
|
41
|
+
```sh
|
|
42
|
+
npm install -g shared-hosting-sync
|
|
43
|
+
shared-hosting-sync --version
|
|
44
|
+
shared-hosting-sync ui
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Alternatively, install a locally built release tarball:
|
|
48
|
+
|
|
49
|
+
```sh
|
|
50
|
+
npm install -g ./artifacts/shared-hosting-sync-0.1.0.tgz
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
For development, install from this checkout:
|
|
54
|
+
|
|
55
|
+
```sh
|
|
56
|
+
npm install
|
|
57
|
+
npm link
|
|
58
|
+
devsync help
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
The SQLite database is built into Node.js; a separate database server or SQLite
|
|
62
|
+
installation is not required. The dashboard stays on this computer.
|
|
63
|
+
|
|
64
|
+
If you installed or linked an earlier development version named `devsync`, remove
|
|
65
|
+
that global package before installing `shared-hosting-sync` to avoid a command
|
|
66
|
+
name conflict:
|
|
67
|
+
|
|
68
|
+
```sh
|
|
69
|
+
npm uninstall -g devsync
|
|
70
|
+
npm install -g ./artifacts/shared-hosting-sync-0.1.0.tgz
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
This replaces the old global installation. Saved projects and credentials remain
|
|
74
|
+
in `~/.devsync/` (or your configured `DEVSYNC_HOME`). For registry installation, use
|
|
75
|
+
`npm install -g shared-hosting-sync` in place of the tarball command.
|
|
76
|
+
|
|
77
|
+
## Start from a project folder
|
|
78
|
+
|
|
79
|
+
Define your hosting settings in the project's `.env`:
|
|
80
|
+
|
|
81
|
+
```dotenv
|
|
82
|
+
DEVSYNC_TRANSPORT=ftps
|
|
83
|
+
DEVSYNC_HOST=ftp.example.com
|
|
84
|
+
DEVSYNC_PORT=21
|
|
85
|
+
DEVSYNC_USERNAME=hosting-user
|
|
86
|
+
DEVSYNC_PASSWORD="hosting-password"
|
|
87
|
+
DEVSYNC_REMOTE_PATH=/public_html/my-site
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
Then run:
|
|
91
|
+
|
|
92
|
+
```sh
|
|
93
|
+
cd my-project
|
|
94
|
+
devsync
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
For a new project, devsync:
|
|
98
|
+
|
|
99
|
+
1. Use the current directory as the local source folder.
|
|
100
|
+
2. Read recognized `DEVSYNC_*` values from its `.env`.
|
|
101
|
+
3. Ask only for missing required settings or corrections to invalid values.
|
|
102
|
+
4. Test the connection and let you browse for a missing server destination.
|
|
103
|
+
5. Save the project and show an upload preview.
|
|
104
|
+
|
|
105
|
+
Complete settings mean no repeated setup questions. Onboarding itself does not
|
|
106
|
+
upload files. After reviewing the preview, upload with:
|
|
107
|
+
|
|
108
|
+
```sh
|
|
109
|
+
devsync deploy
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
The new project is named after its local folder. Use `devsync --label=my-site`
|
|
113
|
+
to choose a name during first-time onboarding. Duplicate names receive a numeric
|
|
114
|
+
suffix automatically.
|
|
115
|
+
|
|
116
|
+
For a registered project, bare `devsync` previews its upload plan. Use an explicit
|
|
117
|
+
sync or deploy command to upload.
|
|
118
|
+
|
|
119
|
+
### Configure entirely in the terminal
|
|
120
|
+
|
|
121
|
+
No `.env` is required. Run `devsync setup` in your project folder and enter the
|
|
122
|
+
missing details. Password input is hidden; during `--edit`, Enter keeps an existing
|
|
123
|
+
password or passphrase. The destination browser lists server
|
|
124
|
+
folders: enter a folder number to open it, `..` to go up, an absolute path to open
|
|
125
|
+
another folder, `.` to select the current folder, or `q` to cancel. Selecting `/`
|
|
126
|
+
requires explicitly choosing `.` at the account root.
|
|
127
|
+
|
|
128
|
+
```sh
|
|
129
|
+
devsync setup # configure this folder and preview
|
|
130
|
+
devsync add my-site ./dist # register a different source folder
|
|
131
|
+
devsync setup my-site # configure that saved project and preview
|
|
132
|
+
devsync setup my-site --edit # revisit connection settings
|
|
133
|
+
devsync setup my-site --browse # select a different server destination
|
|
134
|
+
devsync deploy my-site # upload all eligible files
|
|
135
|
+
devsync sync my-site # upload only changed files
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
Setup tests the connection before saving. It stores a configuration snapshot and
|
|
139
|
+
encrypted credentials outside the project, without rewriting `.env`. Corrections
|
|
140
|
+
to invalid file values apply during that invocation; fix the file too, because
|
|
141
|
+
file values take precedence again on the next run.
|
|
142
|
+
|
|
143
|
+
Without an interactive terminal, supply every required setting through `.env`,
|
|
144
|
+
an explicit environment file, saved settings, or supported options. Incomplete
|
|
145
|
+
setup exits with the missing variable names instead of waiting for input.
|
|
146
|
+
|
|
147
|
+
## Start from anywhere with the UI
|
|
148
|
+
|
|
149
|
+
```sh
|
|
150
|
+
devsync ui
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
The local dashboard opens at `http://127.0.0.1:5180/` by default. Keep the command
|
|
154
|
+
running while using it; press Ctrl+C to stop it.
|
|
155
|
+
|
|
156
|
+
The onboarding flow is:
|
|
157
|
+
|
|
158
|
+
1. Choose **Add project** and browse for a local project folder, or enter its path.
|
|
159
|
+
2. Load hosting settings from that folder's `.env`, if present.
|
|
160
|
+
3. Enter any missing FTP, FTPS, or SFTP details and test the connection.
|
|
161
|
+
4. Browse the server and select the destination folder.
|
|
162
|
+
5. Review the source and destination, name the project, and choose **Save project**.
|
|
163
|
+
|
|
164
|
+
You can enter all settings manually without creating an `.env`. The selected
|
|
165
|
+
project folder determines which `.env` is read, regardless of where you launched
|
|
166
|
+
the dashboard. Saved projects are immediately available to CLI commands too.
|
|
167
|
+
|
|
168
|
+
The local picker starts at your home folder and offers parent navigation, drive
|
|
169
|
+
or filesystem roots, and a path field. The server picker uses the hosting details
|
|
170
|
+
you just entered, so there is no need to save an incomplete project to browse.
|
|
171
|
+
Select an existing server folder with **Use server folder**; `/` is selected only
|
|
172
|
+
when you explicitly choose the account root or supply it in `.env`.
|
|
173
|
+
|
|
174
|
+
Imported passwords are never returned to the browser. Their presence is shown
|
|
175
|
+
beside an empty password field; leave it blank to keep them or enter a replacement.
|
|
176
|
+
Connection testing and browsing use temporary server-side settings. A project is
|
|
177
|
+
saved only after the connection and destination are checked. Cancelled setups
|
|
178
|
+
create no project, and saving performs no upload or remote deletion.
|
|
179
|
+
|
|
180
|
+
Use **Edit setup** on a saved project to revisit its details. Settings loaded from
|
|
181
|
+
`.env` retain precedence on later runs; the dashboard warns when you edit one of
|
|
182
|
+
those settings. The file itself is never changed.
|
|
183
|
+
|
|
184
|
+
After saving, use **Preview uploads** to inspect changed files or all eligible
|
|
185
|
+
files, including their server destinations and exclusions. **Deploy all files**
|
|
186
|
+
uploads every eligible file; **Sync changes** uploads only changed content.
|
|
187
|
+
Enable **Preview only for deploy, sync and watch** to inspect without uploading.
|
|
188
|
+
A saved `DEVSYNC_DRY_RUN=true` setting keeps this option enabled and locked.
|
|
189
|
+
|
|
190
|
+
**Start watching** syncs current files first, then follows local saves.
|
|
191
|
+
**Stop watching** waits for the current batch to finish. Closing the browser tab
|
|
192
|
+
does not stop operations; stopping the `devsync ui` command drains uploads and
|
|
193
|
+
stops its watchers. Restart watching after changing `.env` or `.deployignore`,
|
|
194
|
+
because each watch session uses the settings and exclusions loaded at its start.
|
|
195
|
+
|
|
196
|
+
The dashboard shows file progress, failed files, the last successful sync, and
|
|
197
|
+
the latest 100 activity entries. File lists show up to 200 entries per category;
|
|
198
|
+
excluded directories represent their contents. Activity is held in memory rather
|
|
199
|
+
than a persistent deployment history. A project cannot be edited or run twice
|
|
200
|
+
at once. Shared locks also prevent competing CLI processes or other dashboards
|
|
201
|
+
from operating on that project or overlapping destinations for the same server
|
|
202
|
+
account. The dashboard explains when an operation must be stopped elsewhere.
|
|
203
|
+
|
|
204
|
+
## Environment variables
|
|
205
|
+
|
|
206
|
+
Only recognized devsync keys are read. Unrelated application variables are ignored.
|
|
207
|
+
Blank values count as missing. devsync does not rewrite your application's `.env`.
|
|
208
|
+
|
|
209
|
+
| Variable | Purpose | If omitted |
|
|
210
|
+
| --- | --- | --- |
|
|
211
|
+
| `DEVSYNC_TRANSPORT` | `ftp`, `ftps`, or `sftp` | Ask during setup; FTPS is recommended when supported |
|
|
212
|
+
| `DEVSYNC_HOST` | Hosting hostname or IP, without a URL scheme | Ask during setup |
|
|
213
|
+
| `DEVSYNC_PORT` | Connection port | `21` for FTP/FTPS; `22` for SFTP |
|
|
214
|
+
| `DEVSYNC_USERNAME` | Hosting account username | Ask during setup |
|
|
215
|
+
| `DEVSYNC_PASSWORD` | Hosting password | Ask unless valid SFTP key authentication is configured |
|
|
216
|
+
| `DEVSYNC_PRIVATE_KEY` | Optional local SSH private key path, SFTP only | Use password authentication |
|
|
217
|
+
| `DEVSYNC_REMOTE_PATH` | Destination folder visible to the hosting account | Browse/select during setup; never silently choose `/` |
|
|
218
|
+
|
|
219
|
+
Use the server folder as shown through your FTP account. For some accounts the
|
|
220
|
+
website folder is `/public_html`; others already start inside it. Browse to verify.
|
|
221
|
+
|
|
222
|
+
The precedence is explicit command options, project `.env`, legacy `.devsync.env`,
|
|
223
|
+
saved project settings, then defaults. Only nonblank recognized values override
|
|
224
|
+
lower-priority settings. Ports follow the protocol unless explicitly supplied.
|
|
225
|
+
Relative SFTP key paths are resolved from the selected project folder; `~/` is
|
|
226
|
+
also supported.
|
|
227
|
+
|
|
228
|
+
`--env-file <path>` selects a specific file instead of automatic discovery. It
|
|
229
|
+
overrides the file selected by `DEVSYNC_ENV_FILE`. Relative explicit-file paths
|
|
230
|
+
are resolved from the command's working directory. Files inside the project must
|
|
231
|
+
be named `.env`, `.env.*`, or `.devsync.env` so their credentials remain excluded;
|
|
232
|
+
files outside the project can use any name. See [.env.example](.env.example).
|
|
233
|
+
|
|
234
|
+
These explicit-file options apply to the CLI. UI onboarding always discovers
|
|
235
|
+
settings from the folder selected in the dashboard and ignores `DEVSYNC_ENV_FILE`
|
|
236
|
+
from the process that launched it.
|
|
237
|
+
|
|
238
|
+
Saved projects read automatic configuration relative to their source folder,
|
|
239
|
+
even when operated from another directory. Setup shows each setting's source and
|
|
240
|
+
masks passwords. Supplied invalid values require correction; unrelated app keys
|
|
241
|
+
are never imported into the saved configuration.
|
|
242
|
+
|
|
243
|
+
## CLI controls
|
|
244
|
+
|
|
245
|
+
| Command | Purpose | Status |
|
|
246
|
+
| --- | --- | --- |
|
|
247
|
+
| `devsync` | Onboard an unknown folder, or preview the current registered project | Available |
|
|
248
|
+
| `devsync setup [label]` | Fill missing hosting settings, test the connection, save and preview | Available |
|
|
249
|
+
| `devsync ui` | Open the local browser dashboard from any directory | Available |
|
|
250
|
+
| `devsync add <label> <localPath> [remotePath]` | Register a local source folder and optional destination | Available; run `setup` next |
|
|
251
|
+
| `devsync projects` | List saved projects | Available |
|
|
252
|
+
| `devsync test [label]` | Test a project's hosting connection | Available |
|
|
253
|
+
| `devsync ls [label] [remotePath]` | List server files and folders | Available |
|
|
254
|
+
| `devsync plan [label]` | Preview uploads without writing to the server | Available |
|
|
255
|
+
| `devsync deploy [label]` | Upload all eligible files, including unchanged ones | Available |
|
|
256
|
+
| `devsync sync [label]` | Upload files selected by content comparison | Available |
|
|
257
|
+
| `devsync watch [label]` | Upload eligible changes as you save | Available |
|
|
258
|
+
| `devsync remove <label>` | Remove local project registration | Available |
|
|
259
|
+
| `devsync doctor` | Check local setup | Available |
|
|
260
|
+
| `devsync help` | Show command help | Available |
|
|
261
|
+
|
|
262
|
+
Omit a project label to use the project registered for the current directory.
|
|
263
|
+
Use a label to operate on a saved project from elsewhere.
|
|
264
|
+
|
|
265
|
+
Value options accept both `--name=value` and `--name value` forms. Boolean options
|
|
266
|
+
use `--dry-run` or `--dry-run=false`. Connection/destination
|
|
267
|
+
overrides are `--transport`, `--host`, `--username`, `--port`, and `--remote-path`.
|
|
268
|
+
They apply to the current operation; setup saves the completed configuration.
|
|
269
|
+
Use `.env` or the hidden setup prompt for passwords rather than command arguments.
|
|
270
|
+
Run `devsync help` for all options.
|
|
271
|
+
|
|
272
|
+
For plan and sync commands, `--force` includes files even when their
|
|
273
|
+
contents match. `sync --dry-run` previews without uploading. Watch also supports
|
|
274
|
+
`--dry-run`. Watch observes subsequent changes; run a sync first for an initial
|
|
275
|
+
upload. Stop CLI watching with Ctrl+C.
|
|
276
|
+
|
|
277
|
+
## Choose what to deploy
|
|
278
|
+
|
|
279
|
+
For a frontend application, build locally and select its output folder, such as
|
|
280
|
+
`dist/` or `build/`, as the local source. devsync uploads files; it does not currently
|
|
281
|
+
run builds or install dependencies on the server.
|
|
282
|
+
|
|
283
|
+
For PHP applications, include the application files and required production
|
|
284
|
+
libraries, such as `vendor/`, where appropriate for your hosting layout.
|
|
285
|
+
|
|
286
|
+
**All `node_modules/` folders are currently excluded**, including production
|
|
287
|
+
packages. This is not selective removal of `devDependencies`. Applications that
|
|
288
|
+
need Node.js dependencies on the server require a suitable hosting and dependency
|
|
289
|
+
installation workflow.
|
|
290
|
+
|
|
291
|
+
### .deployignore
|
|
292
|
+
|
|
293
|
+
Registering or scanning a source folder creates `.deployignore` if it is missing.
|
|
294
|
+
It uses gitignore-style patterns:
|
|
295
|
+
|
|
296
|
+
```gitignore
|
|
297
|
+
# Development-only files
|
|
298
|
+
/test/
|
|
299
|
+
/coverage/
|
|
300
|
+
*.log
|
|
301
|
+
|
|
302
|
+
# Local output that should not be deployed
|
|
303
|
+
/backups/
|
|
304
|
+
/scratch/
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
`.gitignore` is not applied by default: files ignored by Git may still be needed
|
|
308
|
+
on the host. Deployment exclusions should describe the files your server needs.
|
|
309
|
+
|
|
310
|
+
The hard blocklist always wins over `.deployignore`, including negation rules:
|
|
311
|
+
|
|
312
|
+
```text
|
|
313
|
+
.env and .env.*
|
|
314
|
+
.devsync.env
|
|
315
|
+
*.pem, *.key, *.p12, *.pfx
|
|
316
|
+
id_rsa, id_rsa.pub, id_ed25519
|
|
317
|
+
.git/, .svn/, .hg/
|
|
318
|
+
node_modules/
|
|
319
|
+
```
|
|
320
|
+
|
|
321
|
+
A local `.env` can configure deployment without becoming part of the upload.
|
|
322
|
+
Provision any server-side application secrets separately.
|
|
323
|
+
|
|
324
|
+
## Deployment behavior and local storage
|
|
325
|
+
|
|
326
|
+
- Sync is a one-way push from the selected local folder to the server.
|
|
327
|
+
- Local deletions are not mirrored; existing server files remain in place.
|
|
328
|
+
- Uploads use a temporary file followed by a rename to reduce partial-file reads.
|
|
329
|
+
- Watch batches rapid changes before uploading.
|
|
330
|
+
- Temporary connection failures get two reconnect attempts, with short increasing
|
|
331
|
+
delays. A retry restarts the entire temporary-file upload, including rename;
|
|
332
|
+
it does not retry an uncertain rename by itself. Authentication, certificate,
|
|
333
|
+
and permission failures require correction rather than automatic retries.
|
|
334
|
+
- An active watcher retries failed transient cycles after five seconds without
|
|
335
|
+
requiring another save. Stop cancels queued retries and drains current work.
|
|
336
|
+
If the initial connection never opens, correct the problem and start again.
|
|
337
|
+
- CLI and UI operations share SQLite locks under `DEVSYNC_HOME`. Watches retain
|
|
338
|
+
their lock until stopped; locks from exited processes are reclaimed on the next
|
|
339
|
+
operation. Separate projects with overlapping paths on the same protocol,
|
|
340
|
+
hostname, port, and username are also blocked. This coordinates one machine and
|
|
341
|
+
one settings store; different stores, machines, hostname aliases, and account
|
|
342
|
+
aliases are not coordinated. Keep `DEVSYNC_HOME` on a local disk.
|
|
343
|
+
- Plan, sync, and watch use the resolved server destination. Missing destinations
|
|
344
|
+
fail before connecting; `/` is allowed only when explicitly configured.
|
|
345
|
+
- Equal-size files are compared using streamed SHA-256 hashes of local and remote
|
|
346
|
+
contents. This reads matching-size remote files over the connection, increasing
|
|
347
|
+
download traffic during previews and syncs. `--force` bypasses content comparison.
|
|
348
|
+
- Upload failures remain visible in the saved project status and make one-time
|
|
349
|
+
sync commands exit unsuccessfully. Directory and inspection errors are surfaced.
|
|
350
|
+
- Settings and encrypted saved credentials live in `~/.devsync/`; set
|
|
351
|
+
`DEVSYNC_HOME` to use another location.
|
|
352
|
+
- The UI runs locally and uses the same saved project store as the CLI.
|
|
353
|
+
|
|
354
|
+
Prefer FTPS or SFTP when your host supports them. Plain FTP sends credentials and
|
|
355
|
+
file contents without encryption.
|
|
356
|
+
FTPS certificates must pass normal certificate verification. Self-signed or
|
|
357
|
+
expired hosting certificates need correction or an appropriately trusted CA;
|
|
358
|
+
devsync does not silently bypass verification.
|
|
359
|
+
|
|
360
|
+
## Development
|
|
361
|
+
|
|
362
|
+
```sh
|
|
363
|
+
npm install
|
|
364
|
+
npm test
|
|
365
|
+
npm run release:check
|
|
366
|
+
```
|
|
367
|
+
|
|
368
|
+
The default test command covers ignore rules, uploads, CLI onboarding/deployments
|
|
369
|
+
against a local FTP server, password prompts, server browsing, SFTP adapter
|
|
370
|
+
contracts, UI onboarding and deployment APIs, watch cycles, configuration, the project database, and encrypted
|
|
371
|
+
credentials. Real local FTP, FTPS, and SFTP servers exercise nested uploads,
|
|
372
|
+
same-size edits, empty files, larger transfers, exclusions, and failures.
|
|
373
|
+
No production hosting account has been used; provider-specific checks remain
|
|
374
|
+
necessary before relying on a particular host.
|
|
375
|
+
|
|
376
|
+
`release:check` runs the suite through the package's prepack gate, checks the
|
|
377
|
+
tarball file list, installs it into a disposable global prefix, and exercises both
|
|
378
|
+
command names, onboarding, FTP deploy/sync, and dashboard assets from another
|
|
379
|
+
directory. It writes a tarball, manifest, and SHA-256 checksum to `artifacts/`.
|
|
380
|
+
Tests, fixtures, development scripts, local state, and credentials are excluded
|
|
381
|
+
from the published package. See [RELEASING.md](RELEASING.md) for the release process.
|
|
382
|
+
|
|
383
|
+
## Buy me a coffee ☕
|
|
384
|
+
|
|
385
|
+
If shared-hosting-sync saves you time, consider buying me a coffee. Your support
|
|
386
|
+
helps keep the project growing.
|
|
387
|
+
|
|
388
|
+
You can send your support to either number:
|
|
389
|
+
|
|
390
|
+
- **+256757035774**
|
|
391
|
+
- **+256789291098**
|
|
392
|
+
|
|
393
|
+
Thank you for supporting the project!
|
|
394
|
+
|
|
395
|
+
## License
|
|
396
|
+
|
|
397
|
+
MIT. See [LICENSE](LICENSE).
|
|
398
|
+
|
|
399
|
+
|
package/RELEASING.md
ADDED
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
# Release shared-hosting-sync
|
|
2
|
+
|
|
3
|
+
The GitHub repository is `kitaroghope/shared-hosting-sync`. The npm package and primary
|
|
4
|
+
command are `shared-hosting-sync`; `devsync` is an equivalent command alias.
|
|
5
|
+
Keep existing `DEVSYNC_*` variables and the settings directory compatible.
|
|
6
|
+
Machines with the old global `devsync` development package should first run
|
|
7
|
+
`npm uninstall -g devsync`, then install the new tarball/package. This avoids
|
|
8
|
+
conflicting command shims and preserves the external settings directory.
|
|
9
|
+
|
|
10
|
+
## Prepare and validate
|
|
11
|
+
|
|
12
|
+
Use Node.js 24 or newer. Update package.json, package-lock.json, and CHANGELOG.md
|
|
13
|
+
for each version. Then run:
|
|
14
|
+
|
|
15
|
+
```sh
|
|
16
|
+
npm ci
|
|
17
|
+
npm run release:check
|
|
18
|
+
npm audit --omit=dev
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
The check runs the full test suite while packing, audits package contents, and
|
|
22
|
+
tests an isolated global installation with production dependencies. Both command
|
|
23
|
+
aliases, SQLite storage, environment onboarding, real FTP deploy/sync, dashboard
|
|
24
|
+
startup, API identity, and UI assets must pass. Nothing is installed into the
|
|
25
|
+
developer's usual global prefix. Generated files are under `artifacts/`:
|
|
26
|
+
|
|
27
|
+
- `shared-hosting-sync-0.1.0.tgz` (version follows package.json)
|
|
28
|
+
- `release.json`, including the complete package file list
|
|
29
|
+
- `SHA256SUMS`
|
|
30
|
+
|
|
31
|
+
The GitHub Release checks workflow runs this on Windows, Linux, and macOS with
|
|
32
|
+
Node.js 24 and uploads each platform's candidate as an artifact. Require all
|
|
33
|
+
three jobs to succeed before publication. A local Windows pass alone is not
|
|
34
|
+
evidence of Linux/macOS compatibility.
|
|
35
|
+
|
|
36
|
+
No tests, test TLS keys, fixtures, scripts, Git metadata, or runtime settings
|
|
37
|
+
belong in the npm package. `prepack` also enforces tests for ordinary `npm pack`
|
|
38
|
+
and source-directory publication. Avoid bypassing lifecycle checks when building.
|
|
39
|
+
|
|
40
|
+
## Authenticate and publish the checked tarball
|
|
41
|
+
|
|
42
|
+
```sh
|
|
43
|
+
npm login
|
|
44
|
+
npm whoami
|
|
45
|
+
npm view shared-hosting-sync name version
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
The registry returned no published record for `shared-hosting-sync` on 21 October
|
|
49
|
+
2026. A 404 does not reserve the name or guarantee publication rights. Confirm
|
|
50
|
+
the signed-in account is the intended maintainer. Use npm's browser sign-in and
|
|
51
|
+
complete any account/2FA requirements personally; do not put tokens into source
|
|
52
|
+
files or chat.
|
|
53
|
+
|
|
54
|
+
Once the account, version, passing CI, package manifest, and checksum are reviewed,
|
|
55
|
+
publish the exact checked archive:
|
|
56
|
+
|
|
57
|
+
```sh
|
|
58
|
+
npm publish ./artifacts/shared-hosting-sync-0.1.0.tgz --access public
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Publishing with `--access public` makes the package contents publicly available. Publishing
|
|
62
|
+
an existing tarball does not rebuild it or rerun the source lifecycle scripts;
|
|
63
|
+
the release check must have passed for this archive beforehand. Never replace a
|
|
64
|
+
published version; fix issues in a new version.
|
|
65
|
+
|
|
66
|
+
## Verify publication
|
|
67
|
+
|
|
68
|
+
```sh
|
|
69
|
+
npm view shared-hosting-sync@0.1.0 name version dist.integrity
|
|
70
|
+
npm install -g shared-hosting-sync@0.1.0
|
|
71
|
+
shared-hosting-sync --version
|
|
72
|
+
devsync --version
|
|
73
|
+
shared-hosting-sync ui
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
Confirm the registry version matches and the installed dashboard opens. Record
|
|
77
|
+
the release commit, archive checksum, and registry integrity. Only then mark
|
|
78
|
+
Phase 6 published and create the corresponding Git tag/release. Provider-specific
|
|
79
|
+
hosting validation remains necessary; tests use local protocol servers.
|
package/package.json
CHANGED
|
@@ -1,6 +1,70 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "shared-hosting-sync",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.1",
|
|
4
|
+
"description": "Deploy and sync local projects to shared hosting over FTP, FTPS, or SFTP, with a CLI and local dashboard.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"license": "MIT",
|
|
7
|
+
"author": "kita",
|
|
8
|
+
"keywords": [
|
|
9
|
+
"ftp",
|
|
10
|
+
"sftp",
|
|
11
|
+
"ftps",
|
|
12
|
+
"deploy",
|
|
13
|
+
"sync",
|
|
14
|
+
"upload",
|
|
15
|
+
"watch",
|
|
16
|
+
"devsync",
|
|
17
|
+
"nodemon",
|
|
18
|
+
"shared-hosting",
|
|
19
|
+
"cpanel",
|
|
20
|
+
"deployignore",
|
|
21
|
+
"developer-tools",
|
|
22
|
+
"cli"
|
|
23
|
+
],
|
|
24
|
+
"repository": {
|
|
25
|
+
"type": "git",
|
|
26
|
+
"url": "git+https://github.com/kitaroghope/shared-hosting-sync.git"
|
|
27
|
+
},
|
|
28
|
+
"bugs": {
|
|
29
|
+
"url": "https://github.com/kitaroghope/shared-hosting-sync/issues"
|
|
30
|
+
},
|
|
31
|
+
"homepage": "https://github.com/kitaroghope/shared-hosting-sync#readme",
|
|
32
|
+
"bin": {
|
|
33
|
+
"shared-hosting-sync": "src/bin.js",
|
|
34
|
+
"devsync": "src/bin.js"
|
|
35
|
+
},
|
|
36
|
+
"engines": {
|
|
37
|
+
"node": ">=24.0.0"
|
|
38
|
+
},
|
|
39
|
+
"files": [
|
|
40
|
+
"src/",
|
|
41
|
+
".env.example",
|
|
42
|
+
"README.md",
|
|
43
|
+
"LICENSE",
|
|
44
|
+
"CHANGELOG.md",
|
|
45
|
+
"RELEASING.md",
|
|
46
|
+
"PHASES.md",
|
|
47
|
+
"PRODUCT.md"
|
|
48
|
+
],
|
|
49
|
+
"scripts": {
|
|
50
|
+
"start": "node src/cli.js",
|
|
51
|
+
"release:check": "node scripts/release-check.js",
|
|
52
|
+
"test": "node test/ignore.test.js && node --test --test-timeout=60000 --test-concurrency=1 test/uploader.test.js test/transport-ftp.test.js test/cli-deployment.test.js test/cli-onboarding.test.js test/onboarding.test.js test/ui-onboarding.test.js test/ui-deployments.test.js test/reliability.test.js test/protocols.test.js test/transport-sftp.test.js test/watcher.test.js test/envResolver.test.js test/db.test.js test/secrets.test.js",
|
|
53
|
+
"prepack": "npm test",
|
|
54
|
+
"prepublishOnly": "npm test"
|
|
55
|
+
},
|
|
56
|
+
"publishConfig": {
|
|
57
|
+
"access": "public"
|
|
58
|
+
},
|
|
59
|
+
"dependencies": {
|
|
60
|
+
"basic-ftp": "^6.2.3",
|
|
61
|
+
"chokidar": "^5.0.0",
|
|
62
|
+
"dotenv": "^17.2.3",
|
|
63
|
+
"ignore": "^7.0.12",
|
|
64
|
+
"ssh2-sftp-client": "^12.1.1"
|
|
65
|
+
},
|
|
66
|
+
"devDependencies": {
|
|
67
|
+
"ftp-srv": "^4.6.3",
|
|
68
|
+
"ssh2": "^1.17.0"
|
|
69
|
+
}
|
|
70
|
+
}
|
package/src/arguments.js
ADDED
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
const VALUE_FLAGS = new Set(['transport', 'env-file', 'remote-path', 'host', 'username', 'port', 'label', 'path'])
|
|
2
|
+
const BOOL_FLAGS = new Set(['dry-run', 'force', 'plan', 'sync', 'edit', 'browse', 'browser', 'help', 'version'])
|
|
3
|
+
|
|
4
|
+
export function parseArgs(argv) {
|
|
5
|
+
let command
|
|
6
|
+
const positional = []
|
|
7
|
+
const flags = {}
|
|
8
|
+
for (let i = 0; i < argv.length; i++) {
|
|
9
|
+
const arg = argv[i]
|
|
10
|
+
if (arg === '-h') { flags.help = true; continue }
|
|
11
|
+
if (arg === '-v') { flags.version = true; continue }
|
|
12
|
+
if (!arg.startsWith('--')) {
|
|
13
|
+
if (command === undefined) command = arg
|
|
14
|
+
else positional.push(arg)
|
|
15
|
+
continue
|
|
16
|
+
}
|
|
17
|
+
const index = arg.indexOf('=')
|
|
18
|
+
const key = arg.slice(2, index === -1 ? undefined : index)
|
|
19
|
+
let value = index === -1 ? undefined : arg.slice(index + 1)
|
|
20
|
+
if (VALUE_FLAGS.has(key)) {
|
|
21
|
+
if (value === undefined && argv[i + 1] && !argv[i + 1].startsWith('--')) value = argv[++i]
|
|
22
|
+
if (value === undefined || value === '') throw new Error(`--${key} requires a value`)
|
|
23
|
+
} else if (BOOL_FLAGS.has(key)) {
|
|
24
|
+
if (value !== undefined && !['true', 'false'].includes(value)) throw new Error(`--${key} must be true or false`)
|
|
25
|
+
value = value === undefined || value === 'true'
|
|
26
|
+
} else throw new Error(`Unknown option --${key}`)
|
|
27
|
+
flags[key] = value
|
|
28
|
+
}
|
|
29
|
+
return { command, positional, flags }
|
|
30
|
+
}
|
package/src/bin.js
ADDED
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// Keep unsupported runtimes out of imports that require built-in SQLite.
|
|
3
|
+
if (Number(process.versions.node.split('.')[0]) < 24) {
|
|
4
|
+
console.error('shared-hosting-sync requires Node.js 24 or newer. Upgrade Node.js and run the command again.')
|
|
5
|
+
process.exitCode = 1
|
|
6
|
+
} else {
|
|
7
|
+
await import('./cli.js')
|
|
8
|
+
}
|
package/src/checksum.js
ADDED
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
import fs from 'node:fs'
|
|
2
|
+
import { createHash } from 'node:crypto'
|
|
3
|
+
import { Writable } from 'node:stream'
|
|
4
|
+
import { pipeline } from 'node:stream/promises'
|
|
5
|
+
|
|
6
|
+
export function hashSink() {
|
|
7
|
+
const hash = createHash('sha256')
|
|
8
|
+
return {
|
|
9
|
+
stream: new Writable({ write(chunk, encoding, callback) { hash.update(chunk); callback() } }),
|
|
10
|
+
digest: () => hash.digest('hex')
|
|
11
|
+
}
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
export async function hashFile(file) {
|
|
15
|
+
const sink = hashSink()
|
|
16
|
+
await pipeline(fs.createReadStream(file), sink.stream)
|
|
17
|
+
return sink.digest()
|
|
18
|
+
}
|