launchr-cli 1.0.0 → 1.1.1

package/.github/workflows/deploy-pages.yml

@@ -0,0 +1,41 @@
+name: Deploy GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - docs/**
+      - .github/workflows/deploy-pages.yml
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

package/.github/workflows/publish-npm.yml

@@ -7,8 +7,21 @@ on:
   release:
     types:
       - published
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: "Run validation only (do not publish to npm)"
+        required: false
+        type: boolean
+        default: true
+      tag:
+        description: "Optional tag to validate (example: v1.2.3)"
+        required: false
+        type: string
+        default: ""
 
 permissions:
+  id-token: write
   contents: read
 
 jobs:
@@ -25,10 +38,18 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: 20
-          registry-url: https://registry.npmjs.org
+          node-version: 24
           cache: npm
 
+      - name: Verify npm version supports trusted publishing
+        run: |
+          NPM_VERSION="$(npm --version)"
+          echo "npm version: ${NPM_VERSION}"
+          if [ "$(printf '%s\n' "11.5.1" "${NPM_VERSION}" | sort -V | head -n1)" != "11.5.1" ]; then
+            echo "npm ${NPM_VERSION} is too old for trusted publishing (requires >=11.5.1)."
+            exit 1
+          fi
+
       - name: Install dependencies
         run: npm ci
 
@@ -40,6 +61,8 @@ jobs:
         run: |
           if [ "${{ github.event_name }}" = "release" ]; then
             TAG="${{ github.event.release.tag_name }}"
+          elif [ "${{ github.event_name }}" = "workflow_dispatch" ] && [ -n "${{ inputs.tag }}" ]; then
+            TAG="${{ inputs.tag }}"
           else
             TAG="${{ github.ref_name }}"
           fi
@@ -50,6 +73,16 @@ jobs:
           PKG_VERSION="$(node -p "JSON.parse(require('fs').readFileSync('package.json', 'utf8')).version")"
           EXPECTED_TAG="v$PKG_VERSION"
 
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ] && [ "${{ inputs.dry_run }}" = "true" ] && [ -z "${{ inputs.tag }}" ]; then
+            echo "Dry run without tag input. Skipping tag/version check."
+            exit 0
+          fi
+
+          if [ -z "${{ steps.tag.outputs.tag }}" ]; then
+            echo "No tag resolved. Provide a tag input like $EXPECTED_TAG for manual publish."
+            exit 1
+          fi
+
           if [ "${{ steps.tag.outputs.tag }}" != "$EXPECTED_TAG" ]; then
             echo "Tag ${{ steps.tag.outputs.tag }} does not match package version $EXPECTED_TAG."
             exit 1
@@ -67,11 +100,25 @@ jobs:
             echo "already_published=false" >> "$GITHUB_OUTPUT"
           fi
 
+      - name: Ensure tokenless trusted publish path
+        if: steps.npm_check.outputs.already_published != 'true' && !(github.event_name == 'workflow_dispatch' && inputs.dry_run)
+        run: |
+          if [ -n "${NODE_AUTH_TOKEN:-}" ] || [ -n "${NPM_TOKEN:-}" ]; then
+            echo "Detected publish token env vars. Trusted publishing should run without npm write tokens."
+            exit 1
+          fi
+
       - name: Publish to npm
-        if: steps.npm_check.outputs.already_published != 'true'
-        run: npm publish --access public
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        if: steps.npm_check.outputs.already_published != 'true' && !(github.event_name == 'workflow_dispatch' && inputs.dry_run)
+        run: npm publish --access public --provenance
+
+      - name: Validate npm publish (dry run)
+        if: github.event_name == 'workflow_dispatch' && inputs.dry_run
+        run: npm publish --access public --dry-run
+
+      - name: Skip publish (dry run)
+        if: github.event_name == 'workflow_dispatch' && inputs.dry_run
+        run: echo "Dry run mode enabled. Publish step skipped."
 
       - name: Skip publish (already published)
         if: steps.npm_check.outputs.already_published == 'true'

package/CONTRIBUTION.md

@@ -0,0 +1,79 @@
+# Contribution Guide
+
+This document covers installation, local development, testing, and release flow for `launchr`.
+
+## Prerequisites
+- Node.js 20+
+- npm
+
+## Installation
+From the repository root:
+
+```bash
+npm install
+npm link
+```
+
+After linking, `launchr` is available in your shell.
+
+## Local Development
+Run the CLI directly from source:
+
+```bash
+npm start
+```
+
+Run with arguments:
+
+```bash
+npm start -- help
+npm start -- list
+```
+
+Use the linked binary:
+
+```bash
+launchr help
+```
+
+## Configuration for Local Testing
+The CLI reads commands from:
+
+`~/.launchr-configurations/launchr-commands.json`
+
+If the file is missing, run:
+
+```bash
+launchr init
+```
+
+or answer `yes` to the auto-create prompt.
+
+## Running Tests
+```bash
+npm test
+```
+
+## Publish to npm (GitHub Actions)
+The workflow is located at:
+
+`.github/workflows/publish-npm.yml`
+
+Publishing is triggered when you:
+- push a tag matching `v*`
+- publish a GitHub Release
+
+Rules:
+- tag must match package version in `package.json` (example: `v1.2.3`)
+- tests must pass before publish
+- if that version already exists on npm, publish is skipped
+
+Required GitHub secret:
+- `NPM_TOKEN` with npm publish access
+
+Typical release flow:
+
+```bash
+npm version patch
+git push origin main --follow-tags
+```

package/README.md

@@ -1,94 +1,59 @@
 # launchr CLI
 
-<p align="center">
-  <img src="assets/launchr-logo.png" alt="launchr logo" width="420">
-</p>
+![launchr](assets/launchr-logo.png)
 
-`launchr` is a configuration-driven CLI to build URLs from typed parameters and open them in your default browser.
+`launchr` is a configuration-driven CLI that turns typed flags into URLs and opens them in your default browser.
 
-Built with:
-- Node.js (ESM)
-- `zx`
-- `fs/promises`
+## Install via npm
+`launchr` requires Node.js 20+.
 
-## Requirements
-- Node.js 20+
+Install globally:
 
-## Install
 ```bash
-npm install
-npm link
+npm install -g launchr-cli
+launchr help
 ```
 
-After linking, `launchr` is available in your shell.
-
-## Publish to npm (GitHub Actions)
-This repository includes an automated workflow at:
-
-`.github/workflows/publish-npm.yml`
-
-It publishes to npm when you either:
-- push a tag matching `v*`
-- publish a GitHub Release
+Run without installing globally:
 
-Rules:
-- tag must match package version in `package.json` (example: `v1.2.3`)
-- tests must pass before publish
-- if that version already exists on npm, publish is skipped
-
-Required GitHub secret:
-- `NPM_TOKEN`: npm automation token with publish access
-
-Typical release flow:
 ```bash
-npm version patch
-git push origin main --follow-tags
+npx launchr-cli help
 ```
 
-## Configuration Location
-`launchr` uses:
+Local development instructions are in [CONTRIBUTION.md](CONTRIBUTION.md).
 
-`~/.launchr-configurations/launchr-commands.json`
+## Product Features
+- Configuration-driven custom commands defined in JSON.
+- Interactive command creation with `launchr add` for command metadata, URL template, and parameter definitions.
+- Typed runtime parameters with support for `string`, `integer`, `boolean`, and `single-choice-list`.
+- Short-flag interface for all parameters (for example `-q`, `-e`, `-t`).
+- Dynamic help and usage output for both built-in and custom commands.
+- URL templating with named placeholders (for example `{query}`) mapped to parameter keys.
+- Automatic config bootstrap prompt when the config file does not exist.
+- Strong validation for config schema, placeholder integrity, unknown flags, required values, types, and allowed values.
 
-If the file is missing, the CLI prompts:
-
-`No configuration found. Do you want to create one? (yes/no)`
-
-If declined, the CLI exits with:
-
-`Configuration file is required to use this CLI.`
-
-## Commands
+## Built-in Commands
 ```bash
 launchr
 launchr help
 launchr list
-launchr init
+launchr add
 launchr <custom-command> help
 launchr <custom-command> [flags]
 ```
 
-## Interactive Setup
-Run:
-```bash
-launchr init
-```
+`launchr init` remains available as a deprecated alias in v1.x and will be removed in v2.0.0.
+
+## Configuration
+Configuration is stored at:
+
+`~/.launchr-configurations/launchr-commands.json`
+
+If the file is missing, `launchr` prompts to create it. If you decline, the CLI exits with:
+
+`Configuration file is required to use this CLI.`
 
-You will be asked for:
-- command name
-- description
-- URL template (with named placeholders like `{query}`)
-- parameters (loop until `done`)
-  - key
-  - type (`string`, `integer`, `boolean`, `single-choice-list`)
-  - flag (`q` means `-q`)
-  - required (`true/false`)
-  - default value
-  - allowed values (for `single-choice-list`)
-
-Type `finish` when asked for command name to stop immediately.
-
-## JSON Example
+## Command Definition Example
 ```json
 {
   "grafana": {
@@ -100,10 +65,7 @@ Type `finish` when asked for command name to stop immediately.
         "flag": "e",
         "defaultValue": "staging",
         "required": true,
-        "values": [
-          "staging",
-          "production"
-        ]
+        "values": ["staging", "production"]
       },
       "query": {
         "type": "string",
@@ -113,38 +75,19 @@ Type `finish` when asked for command name to stop immediately.
       },
       "timeframe": {
         "type": "single-choice-list",
-
         "flag": "t",
         "defaultValue": "5m",
         "required": true,
-        "values": [
-          "5m",
-          "10m",
-          "1h",
-          "6h"
-        ]
+        "values": ["5m", "10m", "1h", "6h"]
       }
     }
   }
 }
 ```
 
-## Usage Examples
+## Usage Example
 ```bash
 launchr list
 launchr grafana help
 launchr grafana -e production -q error -t 5m
 ```
-
-## Validation and Errors
-- schema validation on config load
-- malformed JSON detection
-- required parameter checks
-- type checks (`string`, `integer`, `boolean`, `single-choice-list`)
-- allowed-value checks for `single-choice-list`
-- URL placeholder count checks
-
-## Tests
-```bash
-npm test
-```

package/RELEASE_NOTES_v1.1.0.md

@@ -0,0 +1,15 @@
+# launchr v1.1.0
+
+Command naming transition release.
+
+## Highlights
+
+- Added `launchr add` as the canonical interactive command-definition flow.
+- Kept `launchr init` as a backward-compatible alias in v1.x.
+- Added deprecation warning when alias is used: `"init" is deprecated. Use "launchr add".`
+- Updated help output and documentation to guide users to `launchr add`.
+
+## Transition Policy
+
+- v1.x: `add` is canonical; `init` remains available as deprecated alias.
+- v2.0.0: `init` alias is removed; `add` is the only interactive entrypoint.