Repository navigation
v5: align help and migration docs with lockfile-first scans and service-only vendoring #1289
Copy link
Copy link
Closed
Labels
agent:triagedcompatibilityPublic CLI/JSON, saved state, upgrades, or package-manager compatibility.Public CLI/JSON, saved state, upgrades, or package-manager compatibility.documentationImprovements or additions to documentationImprovements or additions to documentationpriority:p1uxCLI commands, help, diagnostics, output consistency, or actionable recovery instructions.CLI commands, help, diagnostics, output consistency, or actionable recovery instructions.v5-blockerMust resolve before v5: public interface/migration or ordinary patch-install-undo failure.Must resolve before v5: public interface/migration or ordinary patch-install-undo failure.
Description
The primary help text still teaches an installed-package/agent-first model, while v5's primary workflow is patching a fresh checkout's lockfiles and then installing.
Verified from the current source and local CLI help:
- Root help and
scan -hsay:Find patches for installed packages and apply them by rewriting lockfiles to Socket-hosted patched packages. A user with only a lockfile is led to think installation is required first. - Root help calls
repairAgent mode: download missing patch artifacts and clean up unused ones, and groups it only under agent mode. The v5 usage guide also supports repairing missing/corrupt vendored artifacts. - The migration guide omits an actual v4 compatibility break:
--vendor-source build/SOCKET_VENDOR_SOURCE=buildis now rejected, andautono longer falls back to local builds. The v4 argument parser defaulted toautoand offered local builds; the current usage guide documents service-only acquisition.
Sources: Commands help strings, vendored repair documentation.
Before v5, make the first-run instructions match the supported workflow:
- Describe
scanas discovering patches from project dependency/lockfiles, including fresh checkouts; installation is only required where the selected mode/ecosystem actually requires it. - Make it immediately clear that bare
scanwrites hosted references andscan --dry-runpreviews them. - Describe
repairas applicable to existing agent or vendored patch artifacts, while keeping the existing limitation that it cannot recreate a lost vendor ledger. - Keep root, short, and long help consistent with the README/migration guide. No command renaming or new behavior is required.
- Add service-only vendoring to the v5 migration guide: removed
buildvalue/environment configuration,autoalias semantics, no local fallback for missing/pending artifacts, and the distinction between reusing healthy committed artifacts offline and fetching new ones.
Filed during the maintainer-requested v5 interface review. This is a small help correction for the normal lockfile workflow, independent of crash recovery or repeated invocation edge cases.
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
agent:triagedcompatibilityPublic CLI/JSON, saved state, upgrades, or package-manager compatibility.Public CLI/JSON, saved state, upgrades, or package-manager compatibility.documentationImprovements or additions to documentationImprovements or additions to documentationpriority:p1uxCLI commands, help, diagnostics, output consistency, or actionable recovery instructions.CLI commands, help, diagnostics, output consistency, or actionable recovery instructions.v5-blockerMust resolve before v5: public interface/migration or ordinary patch-install-undo failure.Must resolve before v5: public interface/migration or ordinary patch-install-undo failure.
Activity