@fps-plus-sdk/install

Zero-config bootstrap for FPS+ SDK development. Handles corporate proxy/SSL detection, GitHub Packages authentication via gh CLI, and hands off to @ford-innersource/create-fps-app.

Usage

npx --registry=https://registry.npmjs.org @fps-plus-sdk/install@latest

That's it. The CLI will:

Why the --registry flag? Ford developer machines configure @ford-innersource packages to resolve from GitHub Packages. Without the explicit flag, npm may attempt to fetch @fps-plus-sdk/install from GitHub Packages instead of public npmjs.com and fail. The flag ensures it always resolves from the public registry where no auth is required.

1. Detect corporate proxy (ZScaler) — finds the Ford CA certificate and configures NODE_EXTRA_CA_CERTS
2. Authenticate with GitHub via gh CLI — leverages your existing gh installation (opens browser if needed)
3. Save credentials — extracts the token and writes it to ~/.npmrc with restrictive permissions
4. Launch create-fps-app — scaffolds your new project with all auth already working

Prerequisites

• Node.js >= 22
• GitHub CLI (gh) installed
• A GitHub account that is a member of the ford-innersource organization

No npm account, no manual PAT creation, no .npmrc editing required.

Install gh (if you don't have it)

# macOS
brew install gh

# Windows
winget install GitHub.cli

# Linux (Debian/Ubuntu)
sudo apt install gh

What It Does (in detail)

SSL/Proxy Detection

Ford networks use ZScaler for SSL inspection. This causes SELF_SIGNED_CERT_IN_CHAIN errors when npm tries to reach GitHub Packages. The CLI:

• Tests connectivity to npm.pkg.github.com
• If SSL interception is detected, searches known certificate paths
• Writes export NODE_EXTRA_CA_CERTS="<path>" to your shell profile

GitHub Auth via gh

Instead of manually creating a Personal Access Token:

1. CLI checks if gh is already logged in
2. If not, runs gh auth login --web (opens browser, you approve)
3. The one-time code is automatically copied to your clipboard — just paste in the browser
4. After browser auth completes, the CLI auto-continues (no need to press Enter)
5. Extracts the token via gh auth token
6. Writes it to ~/.npmrc for npm to use with GitHub Packages

Scope auto-repair: If your token exists but is missing read:packages, the CLI automatically runs gh auth refresh --scopes read:packages to fix it — no manual steps needed.

Repeat Usage

If you run npx @fps-plus-sdk/install@latest again and valid auth already exists, it skips straight to launching create-fps-app.

Troubleshooting

"gh token doesn't have read:packages scope"

The CLI automatically detects and fixes this. If your existing gh token is missing read:packages, the installer runs gh auth refresh --scopes read:packages without requiring manual intervention. Your browser may open briefly to re-authorize.

If auto-refresh fails for any reason, run manually:

gh auth refresh --scopes read:packages
npx --registry=https://registry.npmjs.org @fps-plus-sdk/install@latest

"Not a member of ford-innersource"

Contact your team lead or GitHub org admin to get added to the ford-innersource organization.

SSL errors persist after setup

The CA cert auto-detection looks in common Ford paths. If your cert is elsewhere:

export NODE_EXTRA_CA_CERTS="/path/to/your/cert.pem"
npx @fps-plus-sdk/install

Development

# Build
npm run build

# Type check
npm run type-check

# Test locally
node dist/index.js

Publishing

1. Create fps-plus-sdk org at npmjs.com/org/create
2. npm run build
3. npm publish --access public