shared-hosting-sync 0.0.0-stage → 0.1.0

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 +16 -0
  3. package/LICENSE +21 -0
  4. package/PHASES.md +141 -0
  5. package/PRODUCT.md +90 -0
  6. package/README.md +407 -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 +198 -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
package/README.md CHANGED
@@ -1,3 +1,408 @@
1
- # Temporary Holding Version
1
+ # shared-hosting-sync
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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
+ ## Current implementation
361
+
362
+ The package is in development. Before relying on it for deployments:
363
+
364
+ - CLI onboarding, `.env` discovery, hidden password prompts, server-folder
365
+ selection, and `deploy` are implemented in Phase 2.
366
+ - Phase 4 adds UI upload previews, deploy/sync, watch start/stop, progress, and
367
+ actionable file errors through the shared deployment engine.
368
+ - Phase 5 adds shared CLI/UI locks, transient connection recovery, watch retries,
369
+ exclusion previews in the CLI, and real local FTPS/SFTP integration checks.
370
+ - Phase 3 adds complete UI onboarding, local/server folder pickers, secure
371
+ imported settings, and reviewed project saving.
372
+ - Phase 1 fixes destination handling, same-size change detection, path validation,
373
+ and failed-sync status. See [PHASES.md](PHASES.md) for the implementation milestones.
374
+ - Phase 6 prepares `shared-hosting-sync@0.1.0`, including production-only packaging,
375
+ global installation checks, and Windows/Linux/macOS release checks in CI.
376
+ See [RELEASING.md](RELEASING.md) for maintainer publication instructions.
377
+
378
+ See [PRODUCT.md](PRODUCT.md) for product requirements and [ROADMAP.md](ROADMAP.md)
379
+ for historical design notes. PHASES.md tracks the current release sequence.
380
+
381
+ ## Development
382
+
383
+ ```sh
384
+ npm install
385
+ npm test
386
+ npm run release:check
387
+ ```
388
+
389
+ The default test command covers ignore rules, uploads, CLI onboarding/deployments
390
+ against a local FTP server, password prompts, server browsing, SFTP adapter
391
+ contracts, UI onboarding and deployment APIs, watch cycles, configuration, the project database, and encrypted
392
+ credentials. Real local FTP, FTPS, and SFTP servers exercise nested uploads,
393
+ same-size edits, empty files, larger transfers, exclusions, and failures.
394
+ No production hosting account has been used; provider-specific checks remain
395
+ necessary before relying on a particular host.
396
+
397
+ `release:check` runs the suite through the package's prepack gate, checks the
398
+ tarball file list, installs it into a disposable global prefix, and exercises both
399
+ command names, onboarding, FTP deploy/sync, and dashboard assets from another
400
+ directory. It writes a tarball, manifest, and SHA-256 checksum to `artifacts/`.
401
+ Tests, fixtures, development scripts, local state, and credentials are excluded
402
+ from the published package. See [RELEASING.md](RELEASING.md) for the release process.
403
+
404
+ ## License
405
+
406
+ MIT. See [LICENSE](LICENSE).
407
+
408
+
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.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
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
+ }
@@ -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
+ }
@@ -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
+ }