Skip to content

Add setup script for Parcel installation - #151

Draft
erayd wants to merge 65 commits into
parcel-pm:masterfrom
erayd:parcel-setup-script
Draft

Add setup script for Parcel installation#151
erayd wants to merge 65 commits into
parcel-pm:masterfrom
erayd:parcel-setup-script

Conversation

@erayd

@erayd erayd commented Aug 20, 2026

Copy link
Copy Markdown
Member

NOTE: This script has been tested and key functionality confirmed to work, but has not yet been source-reviewed. Trust it at your own risk ;-)

Summary

Adds a self-contained bash setup script that handles the parts of Parcel
installation that the webstore extension install cannot: installing the
bootstrap host, generating native messaging manifests for detected browsers,
generating a tailored parcelrc, and optionally building an interactive
.parcel.json ruleset.

Files added

  • src/parcel-setup.sh — Main setup script source. Implements a
    three-phase install flow (detect → preview → apply), interactive
    .parcel.json config builder, and uninstall mode. Compatible with bash 3.2
    and BSD utilities (macOS out-of-the-box). References $BOOTSTRAP_HOST,
    $SETUP_CONFIG, and $SIGNED_HOST_SHA256 as normal variables; in
    development these are loaded from source files.

  • src/parcel-setup.json — Declarative browser/platform/flatpak config.
    Defines 12 browsers (Chrome, Brave, Vivaldi, Edge, Chromium, Arc, Iridium,
    Slimjet, Yandex, LibreWolf, Waterfox, Firefox) with detection paths and
    manifest directories per OS and install level. Parsed with jq at runtime.

  • scripts/generate-setup.sh — Build helper that generates the
    distributable parcel-setup.sh by prepending a heredoc preamble embedding
    the bootstrap host, setup config, and signed host SHA256 hash.

Files modified

  • Makefile — New make setup target generates the distributable script.
    make release now depends on it and includes the setup script in dist/
    (GPG-signed alongside other release artifacts). make clean removes the
    generated file.

  • .gitignore — Added /parcel-setup.sh (generated build artifact).

Key design decisions

  • Single-file distribution: The bootstrap host and setup config are
    embedded as heredocs in the generated parcel-setup.sh. The GPG signature
    on the setup script transitively covers the embedded content.

  • Three-phase install: All detection happens first, proposed changes are
    summarised for user confirmation (default: no), then filesystem
    modifications are made. Partial changes on interrupt are reported, not
    rolled back.

  • Browser detection: Checks both binary paths and existing Parcel
    manifests (not just any NativeMessagingHosts directory — avoids false
    positives from other tools like Browserpass).

  • HOST_HASH pinning: Opt-in via user prompt. The user is asked whether to
    pin the signed host hash in their parcelrc (requiring explicit review of
    future host updates). Never overwrites an existing hash. Not auto-applied
    with --yes.

  • parcelrc customisation: Only nudges settings toward stricter values
    (e.g. custom gpg/jq paths on macOS, HOST_HASH). Never loosens user-set
    values. Inserts below the commented-out default line to keep documentation
    visible.

  • Config builder: Scans the password store, auto-detects rules from
    directory structure (sorted by specificity — more-specific patterns first),
    excludes dotfile directories. Only writes settings that deviate from
    schema defaults or were already present. Never writes internal fields
    (passdir, modified). Existing rules preserved if user declines
    suggestions.

  • --verbose flag: Gates verbose output (e.g. full password-store tree
    listing) for large stores.

CLI flags

Flag Purpose
--system Install system-wide (default if root, requires sudo)
--user Install user-level (no sudo needed)
--prefix <path> Custom installation prefix
--passdir <path> Custom password store directory (overrides PASSWORD_STORE_DIR)
--browser <name> Set up only the specified browser(s)
--flatpak-only Only handle flatpak browsers (skip native)
--yes / -y Non-interactive: accept all detected defaults
--create-config Run the .parcel.json config builder only
--uninstall Remove the installation (preserves parcelrc and .parcel.json)
--remove-config With --uninstall: also remove config files
--verbose Show verbose output

Testing

  • make setup generates a valid, syntactically-correct distributable
  • End-to-end install/uninstall verified on macOS (Chrome, Edge, Firefox)
  • Manifests use correct format (chromium: allowed_origins, firefox:
    allowed_extensions)
  • Smoke tests pass (parcelrc created, customisations applied stricter-only)
  • make prettier passes
  • make test — all 450 existing tests pass, 0 failures
  • No automated test harness for the setup script itself — the target
    environments are too varied to automate meaningfully (manual UAT across
    representative environments required)

Adds a self-contained bash setup script (src/parcel-setup.sh) with
declarative browser config (src/parcel-setup.json) that handles bootstrap
host installation, native messaging manifest generation, parcelrc
customisation, interactive .parcel.json config building, and uninstall.
Includes a build helper (scripts/generate-setup.sh) that embeds the
bootstrap host and config as heredocs to produce the distributable
parcel-setup.sh. Adds `make setup` target and integrates it into
`make release`.
@erayd erayd self-assigned this Aug 20, 2026
@erayd erayd added ux This relates to the end-user's experience tooling This relates to the supporting tooling, not the extension or native host labels Aug 20, 2026
@erayd erayd moved this from Backlog to In progress in Release Dashboard Aug 23, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

tooling This relates to the supporting tooling, not the extension or native host ux This relates to the end-user's experience

Projects

Status: In progress

Development

Successfully merging this pull request may close these issues.

1 participant