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
package/.env.example ADDED
@@ -0,0 +1,23 @@
1
+ # Add these keys to your project's .env, then run devsync from that folder.
2
+ # Only DEVSYNC_* keys are read. The file is never uploaded or rewritten.
3
+
4
+ # ftp | ftps | sftp (choose a protocol supported by your hosting account).
5
+ DEVSYNC_TRANSPORT=ftps
6
+
7
+ # Hostname or IP only, without a URL scheme.
8
+ DEVSYNC_HOST=ftp.example.com
9
+ DEVSYNC_USERNAME=hosting-user
10
+ DEVSYNC_PASSWORD=""
11
+
12
+ # Optional: defaults to 21 for FTP/FTPS, 22 for SFTP.
13
+ DEVSYNC_PORT=
14
+
15
+ # Leave blank to browse and select an existing server folder during setup.
16
+ DEVSYNC_REMOTE_PATH=
17
+
18
+ # Optional SFTP key path, relative to this project or absolute.
19
+ # DEVSYNC_PRIVATE_KEY=~/.ssh/id_ed25519
20
+
21
+ # Optional behavior.
22
+ # DEVSYNC_DRY_RUN=true
23
+ # DEVSYNC_DEBOUNCE_MS=400
package/CHANGELOG.md ADDED
@@ -0,0 +1,24 @@
1
+ # Changelog
2
+
3
+ ## 0.1.1 — 26 October 2026
4
+
5
+ - Fix dashboard “Edit setup” so saved projects can change their local folder,
6
+ including after the original folder has moved.
7
+ - Retain the existing project, saved credentials, and server destination when
8
+ changing folders, and load environment settings from the replacement folder.
9
+ - Reject replacement folders already assigned to another project.
10
+
11
+ ## 0.1.0 — 21 October 2026
12
+
13
+ First release of shared-hosting-sync, developed under the devsync name.
14
+
15
+ - Global `shared-hosting-sync` command with `devsync` as an alias.
16
+ - Terminal and local dashboard onboarding, project-folder environment discovery,
17
+ encrypted saved credentials, and local/server folder selection.
18
+ - FTP, verified FTPS, and SFTP previews, deploy, changed-file sync, and watching.
19
+ - Content comparison, enforced secret/dependency exclusions, temporary-file
20
+ uploads, progress, activity, and file-level errors.
21
+ - Shared local CLI/UI operation locks, bounded connection recovery, and watch retries.
22
+
23
+ Requires Node.js 24 or newer. Remote deletions, builds, dependency installation,
24
+ deployment history, and rollback are not included. See README.md for behavior.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 kita
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/PHASES.md ADDED
@@ -0,0 +1,147 @@
1
+ # Development phases
2
+
3
+ ## Phase 1: Deployment foundation — implemented 21 October 2026
4
+
5
+ - Plan, sync, and watch pass the resolved destination to the uploader.
6
+ - `add` persists its optional destination argument.
7
+ - Missing destinations fail instead of implicitly uploading to `/`; explicitly
8
+ configured `/` remains valid. Relative destinations, traversal, control
9
+ characters, and local sources outside the selected folder are rejected.
10
+ - Same-size files require matching SHA-256 contents before they are skipped.
11
+ Remote files are streamed for comparison, with no full-file buffering or
12
+ remote shell requirement. This adds inbound network traffic.
13
+ - Directory creation and file inspection errors are surfaced. Failed syncs keep
14
+ an error status and return a nonzero exit code; watch reports failed cycles.
15
+ - Project `.devsync.env` resolution follows the selected project rather than the
16
+ launch directory. The file is always excluded from deployment.
17
+ - SFTP stat, directory creation, and deletion calls match the installed library.
18
+
19
+ Validation includes a real local FTP server and CLI subprocesses for destination
20
+ selection, previews, first upload, same-size edits, unchanged files, and failed
21
+ uploads. Uploader, watch, SFTP adapter, configuration, database, and secret tests
22
+ are also included in `npm test`. Real SFTP/FTPS server validation is still pending;
23
+ no production hosting account was used.
24
+
25
+ ## Phase 2: Complete CLI — implemented 21 October 2026
26
+
27
+ - Bare `devsync` onboards unknown folders from `.env` and previews without upload.
28
+ - `setup [label]` fills missing/invalid details, hides password input, tests the
29
+ connection, browses for an unspecified destination, saves, and previews.
30
+ - `setup --edit` revisits connection settings; `setup --browse` selects a new
31
+ destination. The folder browser supports numbered directories, parent
32
+ navigation, absolute paths, explicit current-folder selection, and cancellation.
33
+ - `deploy` uploads all eligible files; `sync` uploads changed content. Both support
34
+ previews and operate on saved projects from any working directory.
35
+ - Shared resolution applies command overrides, project `.env`, legacy
36
+ `.devsync.env`, saved settings, and defaults. Explicit files replace automatic
37
+ discovery. Relative SFTP keys follow the selected project folder.
38
+ - Setup saves a shared snapshot atomically, encrypts credentials, ignores unrelated
39
+ app values, and never rewrites `.env`. File values remain authoritative on later
40
+ invocations. Failed or cancelled new setup leaves no project registration.
41
+ - Complete settings work noninteractively. Missing settings fail promptly with
42
+ variable names. The environment example and command documentation are current.
43
+
44
+ Validation includes prompt/browsing tests, configuration precedence, atomic saved
45
+ settings, and real FTP CLI onboarding, previews, deploy/sync behavior, failed
46
+ authentication, saved credentials, and operation from another directory.
47
+
48
+ ## Phase 3: UI onboarding — implemented 21 October 2026
49
+
50
+ - The dashboard guides users through local folder, hosting, destination, and
51
+ review steps. Local browsing supports home, drives/roots, parent navigation,
52
+ and manual absolute paths, independent of the launch directory.
53
+ - Selecting a source folder loads its `.env` and legacy `.devsync.env`; the UI
54
+ ignores the launch environment's `DEVSYNC_ENV_FILE`. Missing settings are entered
55
+ manually, and supplied secrets are represented only by presence flags.
56
+ - New projects remain temporary drafts until a successful connection test, valid
57
+ existing destination, and final review/save. Cancellation, failed login, missing
58
+ destinations, duplicate names, and invalid settings leave no new registration.
59
+ - The server folder picker uses unsaved hosting details. Changes to connection
60
+ details invalidate the test. Save rechecks the destination without uploading
61
+ or deleting remote files, then stores the shared encrypted configuration.
62
+ - Saved projects can be viewed, edited, connection-tested, removed locally, and
63
+ used immediately through CLI commands. Configuration sources and file precedence
64
+ are visible; application `.env` files remain untouched.
65
+ - The loopback service checks request hosts/origins and requires a session token
66
+ for local browsing and draft APIs. Static assets are explicitly whitelisted.
67
+
68
+ Validation covers HTTP onboarding against a real local FTP server, directory
69
+ navigation, secret redaction, manual settings, cancellation, invalid/authentication
70
+ failures, CLI compatibility, draft expiry, and origin/host checks. The actual
71
+ browser flow was exercised for imported credentials, folder selection, review,
72
+ save, editing, manual entry, and cancellation.
73
+
74
+ ## Phase 4: UI deployment — implemented 21 October 2026
75
+
76
+ - Saved projects offer changed/all-file previews, deploy, sync, and watch controls
77
+ through the same configuration, exclusions, and uploader used by the CLI.
78
+ - Previews show destinations, unchanged files, and excluded entries without
79
+ writing remote files. Request-level and saved dry-run settings prevent uploads.
80
+ - Background operations expose file progress, completion, failed files, last
81
+ successful sync, and the latest 100 activity entries. Plan lists are capped at
82
+ 200 entries per category; counts remain complete.
83
+ - Watching performs an initial sync, then follows saves. Stopping drains the
84
+ current batch and discards pending work; server shutdown also drains operations.
85
+ Closing or refreshing a browser tab leaves the server-side operation running.
86
+ - Dashboard actions cannot overlap for one project, and active projects cannot
87
+ be edited or removed there. Phase 5 extends this across CLI/UI processes.
88
+
89
+ Validation includes real FTP HTTP operations, read-only previews, same-size edits,
90
+ dry-run settings, watch readiness/stop behavior, shutdown, concurrent-action guards,
91
+ progress, and failed uploads. Browser checks cover deploy, unchanged sync, watching
92
+ across refresh, stopping, previews, failure display, and successful retry.
93
+
94
+ ## Phase 5: Reliability and testing — implemented 21 October 2026
95
+
96
+ - SQLite operation locks coordinate CLI commands and multiple dashboards sharing
97
+ the same local settings store. Watches retain ownership until stopped.
98
+ Overlapping paths for the same protocol/host/port/account are guarded even when
99
+ registered as different projects. Exited owners are reclaimed without expiring
100
+ live transfers. Settings changes/removal also acquire project ownership.
101
+ - Transient connection failures receive two bounded reconnect attempts. Read
102
+ operations can be retried; uploads restart the whole temporary-write/rename
103
+ sequence, including when a rename acknowledgement is lost. Permanent login,
104
+ permission, and certificate errors remain visible without repeated attempts.
105
+ - Active watchers schedule another cycle after transient failures without another
106
+ save. Stop clears retry work and waits for an in-flight cycle. CLI notices and
107
+ dashboard activity expose reconnect attempts and operation conflicts.
108
+ - CLI previews list custom and hard exclusions, matching the dashboard. Existing
109
+ secret and dependency exclusions remain enforced in all upload paths.
110
+ - Real local FTPS and SFTP servers cover read-only preview, nested destinations,
111
+ empty and multi-chunk files, same-size edits, unchanged files, exclusions, and
112
+ failed uploads. FTPS now verifies certificates; tests explicitly trust a public
113
+ localhost fixture and prove untrusted certificates are rejected.
114
+
115
+ Validation also covers dropped real FTP connections, safe replay after lost
116
+ rename responses, bounded retries, watcher recovery/stop, separate-process lock
117
+ conflicts, crashed owners, and dashboard/CLI coordination. Locks are local to one
118
+ machine/settings store and do not detect remote aliases or other deployment tools.
119
+ Production-host checks and cross-platform installation remain release work.
120
+
121
+ ## Phase 6: npm release — 0.1.0 published 21 October 2026
122
+
123
+ - Package and primary command renamed to `shared-hosting-sync`; `devsync` remains
124
+ an alias, with compatible settings and environment variables.
125
+ - Repository links, shared CLI/API version information, and Node.js >=24 runtime
126
+ requirements are finalized. The executable reports a clear upgrade message on
127
+ older runtimes before importing SQLite.
128
+ - The tarball allowlist contains runtime source, UI assets, migrations, the safe
129
+ environment example, README, changelog, and license. Tests, TLS fixture keys,
130
+ local state, and development scripts are excluded.
131
+ - `release:check` packs through the complete test gate, audits contents, installs
132
+ into a disposable global prefix, and checks both aliases plus onboarding,
133
+ real FTP deployment/sync, dashboard startup, assets, and version metadata.
134
+ - A Node.js 24 workflow runs release checks on Windows, Linux, and macOS. Generated
135
+ tarballs, manifests, and SHA-256 checksums are saved as CI artifacts.
136
+ - Publication requires maintainer authentication, all platform checks, and
137
+ registry acceptance. Registry installation confirms publication; see RELEASING.md
138
+ for the verification steps.
139
+
140
+ Published [shared-hosting-sync@0.1.0](https://www.npmjs.com/package/shared-hosting-sync/v/0.1.0)
141
+ with `latest` pointing to 0.1.0. Windows, Linux, and macOS release checks passed.
142
+ The registry tarball matches the validated archive byte for byte (SHA-256
143
+ `e2301a79bc1aa64f28262b929c7b57c9447dfba6c82bc2c5b56b0b476f2c6a6e`).
144
+ A fresh registry installation verified both command aliases and SQLite startup.
145
+
146
+ After release: GitHub Actions integration, deployment history, rollback, and
147
+ optional remote deletion.
package/PRODUCT.md ADDED
@@ -0,0 +1,90 @@
1
+ # shared-hosting-sync product requirements
2
+
3
+ Published package/primary command: `shared-hosting-sync`. The `devsync` command
4
+ alias and `DEVSYNC_*` configuration names remain supported.
5
+
6
+ devsync is a global npm package for deploying local projects to shared hosting.
7
+ The CLI and local browser UI are first-class alternative controls. Users must be
8
+ able to complete the workflow through either interface.
9
+
10
+ ## Required in both interfaces
11
+
12
+ - Register, configure, list, and remove projects.
13
+ - Enter hosting credentials and choose FTP, FTPS, or SFTP.
14
+ - Select a local source folder and browse/select a remote destination.
15
+ - Test connections and preview uploads and exclusions.
16
+ - Deploy once, sync changed files, and start/stop continuous watching.
17
+ - View progress, completion, and actionable errors.
18
+
19
+ Both interfaces must share project settings, credential handling, ignore rules,
20
+ and deployment operations. A project created through one must work in the other.
21
+ CLI setup must not require the UI. Once `devsync ui` is launched, the UI workflow
22
+ must not require further terminal commands.
23
+
24
+ ## Current gaps (21 October 2026)
25
+
26
+ As of 21 October 2026, the CLI supports `.env` onboarding, terminal-only credential
27
+ setup, destination browsing, preview, deploy, sync, and watch. The UI now supports
28
+ complete folder selection, `.env` discovery, hosting details, connection testing,
29
+ server browsing, review, and project saving, plus upload previews, deployment,
30
+ changed-file sync, watch start/stop, progress, and file errors. Both interfaces
31
+ support the core workflow. Connection recovery, shared-store cross-process locks,
32
+ and real local FTP/FTPS/SFTP validation are implemented. Production-host checks,
33
+ cross-platform installation, and npm release preparation remain pending.
34
+
35
+ ## Setup paths
36
+
37
+ ### Automatic setup from a project's .env
38
+
39
+ Running `devsync` in an unregistered project directory must detect documented
40
+ `DEVSYNC_*` keys in that directory's `.env`, use the current directory as the
41
+ local source, and ask only for missing required settings. With complete valid
42
+ settings, setup needs no repeated questions. Show an upload preview before the
43
+ first deployment; launching onboarding must not itself upload files.
44
+
45
+ Supported connection and destination variables:
46
+
47
+ ```dotenv
48
+ DEVSYNC_TRANSPORT=ftps
49
+ DEVSYNC_HOST=ftp.example.com
50
+ DEVSYNC_PORT=21
51
+ DEVSYNC_USERNAME=hosting-user
52
+ DEVSYNC_PASSWORD="hosting-password"
53
+ # Optional during discovery: select this in onboarding if omitted.
54
+ DEVSYNC_REMOTE_PATH=/public_html/my-site
55
+ ```
56
+
57
+ Only read recognized devsync keys; do not import unrelated application secrets.
58
+ Blank values count as missing. Derive an omitted port from the chosen protocol.
59
+ A missing remote destination must trigger a selection step rather than silently
60
+ targeting `/`. Supplied invalid values require correction rather than repeated
61
+ entry of valid settings. Document these variables and defaults in README.md when
62
+ the behavior ships.
63
+
64
+ For a saved project, resolve files relative to its local source folder rather
65
+ than whichever directory the user later launches devsync from. Explicit options
66
+ take precedence over project environment values, which take precedence over
67
+ saved settings and then defaults. Show configuration sources, mask passwords,
68
+ and keep `.env` excluded from deployment. Read configuration without rewriting
69
+ the application's `.env`.
70
+
71
+ ### UI onboarding from any directory
72
+
73
+ `devsync ui` must launch the local dashboard regardless of the current directory.
74
+ The Add Project flow must let the user:
75
+
76
+ 1. Browse and select a local project folder, with manual path entry available.
77
+ 2. Load recognized settings from that selected folder's `.env`, when present.
78
+ 3. Enter only missing hosting details and test the connection.
79
+ 4. Browse the server and select the destination folder.
80
+ 5. Save the project, preview uploads, and deploy or start watching.
81
+
82
+ The selected project folder determines configuration discovery; the directory
83
+ used to launch the dashboard must not supply credentials for a different project.
84
+ Users may also enter all hosting details manually without creating an `.env`.
85
+ Projects onboarded in the UI must immediately work through the CLI and vice versa.
86
+
87
+ The CLI setup path is implemented. Resolution reads `.env` and legacy `.devsync.env`
88
+ from the selected project folder; explicit files and command options are supported.
89
+ UI onboarding and deployment controls are implemented. See PHASES.md for
90
+ implementation milestones and remaining reliability work.