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/.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.
|