launchr-cli 1.0.0

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

@@ -0,0 +1,78 @@
+name: Publish npm Package
+
+on:
+  push:
+    tags:
+      - "v*"
+  release:
+    types:
+      - published
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    concurrency:
+      group: npm-publish-${{ github.event.release.tag_name || github.ref_name }}
+      cancel-in-progress: false
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm test
+
+      - name: Resolve tag name
+        id: tag
+        run: |
+          if [ "${{ github.event_name }}" = "release" ]; then
+            TAG="${{ github.event.release.tag_name }}"
+          else
+            TAG="${{ github.ref_name }}"
+          fi
+          echo "tag=$TAG" >> "$GITHUB_OUTPUT"
+
+      - name: Verify tag matches package version
+        run: |
+          PKG_VERSION="$(node -p "JSON.parse(require('fs').readFileSync('package.json', 'utf8')).version")"
+          EXPECTED_TAG="v$PKG_VERSION"
+
+          if [ "${{ steps.tag.outputs.tag }}" != "$EXPECTED_TAG" ]; then
+            echo "Tag ${{ steps.tag.outputs.tag }} does not match package version $EXPECTED_TAG."
+            exit 1
+          fi
+
+      - name: Check if this version already exists on npm
+        id: npm_check
+        run: |
+          PKG_NAME="$(node -p "JSON.parse(require('fs').readFileSync('package.json', 'utf8')).name")"
+          PKG_VERSION="$(node -p "JSON.parse(require('fs').readFileSync('package.json', 'utf8')).version")"
+
+          if npm view "${PKG_NAME}@${PKG_VERSION}" version >/dev/null 2>&1; then
+            echo "already_published=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "already_published=false" >> "$GITHUB_OUTPUT"
+          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 }}
+
+      - name: Skip publish (already published)
+        if: steps.npm_check.outputs.already_published == 'true'
+        run: echo "This package version is already published. Skipping."

package/README.md

@@ -0,0 +1,150 @@
+# launchr CLI
+
+<p align="center">
+  <img src="assets/launchr-logo.png" alt="launchr logo" width="420">
+</p>
+
+`launchr` is a configuration-driven CLI to build URLs from typed parameters and open them in your default browser.
+
+Built with:
+- Node.js (ESM)
+- `zx`
+- `fs/promises`
+
+## Requirements
+- Node.js 20+
+
+## Install
+```bash
+npm install
+npm link
+```
+
+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
+
+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
+```
+
+## Configuration Location
+`launchr` uses:
+
+`~/.launchr-configurations/launchr-commands.json`
+
+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
+```bash
+launchr
+launchr help
+launchr list
+launchr init
+launchr <custom-command> help
+launchr <custom-command> [flags]
+```
+
+## Interactive Setup
+Run:
+```bash
+launchr init
+```
+
+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
+```json
+{
+  "grafana": {
+    "description": "some useful information",
+    "url": "https://grafana.com/{environments}/{query}/{timeframe}",
+    "parameters": {
+      "environments": {
+        "type": "single-choice-list",
+        "flag": "e",
+        "defaultValue": "staging",
+        "required": true,
+        "values": [
+          "staging",
+          "production"
+        ]
+      },
+      "query": {
+        "type": "string",
+        "flag": "q",
+        "defaultValue": "error",
+        "required": true
+      },
+      "timeframe": {
+        "type": "single-choice-list",
+
+        "flag": "t",
+        "defaultValue": "5m",
+        "required": true,
+        "values": [
+          "5m",
+          "10m",
+          "1h",
+          "6h"
+        ]
+      }
+    }
+  }
+}
+```
+
+## Usage Examples
+```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.0.0.md

@@ -0,0 +1,11 @@
+# launchr v1.0.0
+
+First stable release of `launchr`, a config-driven CLI to build URLs from typed flags and open them in your default browser.
+
+## Highlights
+
+- Interactive setup with `launchr init` to create custom commands and URL templates.
+- Typed parameter support: `string`, `integer`, `boolean`, `single-choice-list`.
+- Runtime checks for required params, unknown flags, invalid values, and URL placeholders.
+- URL interpolation with encoding plus cross-platform browser launch (`open` / `cmd start` / `xdg-open`).
+- Automated npm publish workflow with test gate and version/tag verification.

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "launchr-cli",
+  "version": "1.0.0",
+  "description": "Config-driven URL launcher CLI built with Node.js + zx",
+  "type": "module",
+  "bin": {
+    "launchr": "./src/cli.mjs"
+  },
+  "scripts": {
+    "start": "node ./src/cli.mjs",
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "zx": "^8.8.4"
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+
+import os from "node:os";
+import { realpathSync } from "node:fs";
+import process from "node:process";
+import { pathToFileURL } from "node:url";
+import { buildGeneralHelp, buildCommandHelp, buildUsageText } from "./commands/help.mjs";
+import { runInitFlow } from "./commands/init.mjs";
+import { buildCommandList } from "./commands/list.mjs";
+import { runCustomCommand } from "./commands/run-custom.mjs";
+import { getConfigDirPath, getConfigFilePath } from "./config/paths.mjs";
+import {
+  ensureConfigExistsOrPromptCreate,
+  loadConfiguration,
+  saveConfiguration,
+} from "./config/store.mjs";
+import { parseArgv } from "./parsing/argv.mjs";
+import { promptYesNo, createPrompter } from "./utils/prompt.mjs";
+import { UsageError } from "./utils/errors.mjs";
+import { openInBrowser } from "./utils/browser.mjs";
+
+function writeLine(stream, message = "") {
+  stream.write(`${message}\n`);
+}
+
+export async function runCli(argv = process.argv.slice(2), options = {}) {
+  const stdout = options.stdout ?? process.stdout;
+  const stderr = options.stderr ?? process.stderr;
+  const input = options.input ?? process.stdin;
+  const homeDir = options.homeDir ?? os.homedir();
+  const promptYesNoFn = options.promptYesNoFn ?? promptYesNo;
+  const createPrompterFn = options.createPrompterFn ?? createPrompter;
+  const openUrlFn = options.openUrlFn ?? openInBrowser;
+
+  const configDirPath = getConfigDirPath(homeDir);
+  const configFilePath = getConfigFilePath(homeDir);
+
+  try {
+    await ensureConfigExistsOrPromptCreate({
+      configDirPath,
+      configFilePath,
+      promptYesNo: (question) => promptYesNoFn(question, { input, output: stdout }),
+    });
+
+    let config = await loadConfiguration(configFilePath);
+    const parsed = parseArgv(argv);
+
+    if (!parsed.command) {
+      writeLine(stdout, buildUsageText(config));
+      return 0;
+    }
+
+    if (parsed.command === "help") {
+      writeLine(stdout, buildGeneralHelp(config));
+      return 0;
+    }
+
+    if (parsed.command === "list") {
+      writeLine(stdout, buildCommandList(config));
+      return 0;
+    }
+
+    if (parsed.command === "init") {
+      const prompter = createPrompterFn({ input, output: stdout });
+      try {
+        config = await runInitFlow({
+          config,
+          prompter,
+          saveConfig: (nextConfig) => saveConfiguration(configFilePath, nextConfig),
+        });
+        if (Object.keys(config).length > 0) {
+          writeLine(stdout, buildCommandList(config));
+        }
+      } finally {
+        prompter.close();
+      }
+      return 0;
+    }
+
+    const commandConfig = config[parsed.command];
+    if (!commandConfig) {
+      throw new UsageError(`Unknown command "${parsed.command}". Run "launchr list" to see available commands.`);
+    }
+
+    if (parsed.rest[0] === "help") {
+      writeLine(stdout, buildCommandHelp(parsed.command, commandConfig));
+      return 0;
+    }
+
+    const result = await runCustomCommand({
+      commandName: parsed.command,
+      commandConfig,
+      argv: parsed.rest,
+      openUrl: openUrlFn,
+    });
+    writeLine(stdout, `Opening URL: ${result.finalUrl}`);
+    return 0;
+  } catch (error) {
+    writeLine(stderr, error.message);
+    return 1;
+  }
+}
+
+function isDirectInvocation() {
+  if (!process.argv[1]) {
+    return false;
+  }
+
+  const argvPath = process.argv[1];
+  const argvHref = pathToFileURL(argvPath).href;
+  if (import.meta.url === argvHref) {
+    return true;
+  }
+
+  try {
+    const resolvedArgvPath = realpathSync(argvPath);
+    const resolvedArgvHref = pathToFileURL(resolvedArgvPath).href;
+    return import.meta.url === resolvedArgvHref;
+  } catch {
+    return false;
+  }
+}
+
+if (isDirectInvocation()) {
+  const code = await runCli();
+  process.exitCode = code;
+}

package/src/commands/help.mjs

@@ -0,0 +1,101 @@
+const BUILTIN_COMMANDS = [
+  { name: "help", description: "Show manual" },
+  { name: "list", description: "List available commands" },
+  { name: "init", description: "Interactive setup" },
+];
+
+function formatRequired(required) {
+  return required ? "required" : "optional";
+}
+
+function formatParameterType(parameterDefinition) {
+  if (parameterDefinition.type === "single-choice-list") {
+    return `Allowed values: ${parameterDefinition.values.join(", ")}`;
+  }
+  return `Type: ${parameterDefinition.type}`;
+}
+
+function normalizeDescription(rawDescription) {
+  if (typeof rawDescription !== "string") {
+    return "No description";
+  }
+
+  const trimmed = rawDescription.trim();
+  return trimmed.length > 0 ? trimmed : "No description";
+}
+
+function formatCommandRows(commandRows) {
+  if (commandRows.length === 0) {
+    return ["  (none)"];
+  }
+
+  const nameWidth = commandRows.reduce((maxWidth, row) => {
+    return Math.max(maxWidth, row.name.length);
+  }, 0);
+
+  return commandRows.map((row) => {
+    return `  ${row.name.padEnd(nameWidth)}  ${row.description}`;
+  });
+}
+
+export function buildUsageText(config = {}) {
+  const customCommandRows = Object.entries(config).map(([commandName, commandConfig]) => {
+    return {
+      name: commandName,
+      description: normalizeDescription(commandConfig?.description),
+    };
+  });
+
+  return [
+    "Usage: launchr <command> [options]",
+    "",
+    "Built-in Commands:",
+    ...formatCommandRows(BUILTIN_COMMANDS),
+    "",
+    "Custom Commands:",
+    ...formatCommandRows(customCommandRows),
+  ].join("\n");
+}
+
+export function buildGeneralHelp(config = {}) {
+  const usageText = buildUsageText(config);
+  return [
+    usageText,
+    "",
+    "How to define commands:",
+    "  Run `launchr init` and follow prompts to create command metadata, URL templates, and parameters.",
+    "",
+    "How parameters work:",
+    "  Each parameter has a type, a short flag, required/default rules, and optional allowed values.",
+    "  URL templates use named placeholders like `{query}` mapped by parameter key.",
+    "",
+    "Examples:",
+    "  launchr list",
+    "  launchr grafana help",
+    "  launchr grafana -e production -q error -t 5m",
+  ].join("\n");
+}
+
+export function buildCommandHelp(commandName, commandConfig) {
+  const parameterEntries = Object.entries(commandConfig.parameters);
+
+  const usageTokens = parameterEntries.map(([paramName, definition]) => {
+    const token = `-${definition.flag.replace(/^-+/, "")} <${paramName}>`;
+    return definition.required ? token : `[${token}]`;
+  });
+
+  const optionLines = [];
+  for (const [parameterName, definition] of parameterEntries) {
+    const normalizedFlag = definition.flag.replace(/^-+/, "");
+    optionLines.push(`  -${normalizedFlag}   ${parameterName} (${formatRequired(definition.required)})`);
+    optionLines.push(`       ${formatParameterType(definition)}`);
+  }
+
+  return [
+    "Usage:",
+    `  launchr ${commandName}${usageTokens.length > 0 ? ` ${usageTokens.join(" ")}` : ""}`,
+    "",
+    "Options:",
+    ...(optionLines.length > 0 ? optionLines : ["  (No parameters defined)"]),
+  ].join("\n");
+}

package/src/commands/init.mjs

@@ -0,0 +1,198 @@
+import { PARAMETER_TYPES } from "../constants.mjs";
+import { ValidationError } from "../utils/errors.mjs";
+
+function normalizeFlag(rawFlag) {
+  const flag = rawFlag.replace(/^-+/, "").trim();
+  if (!/^[a-zA-Z]$/.test(flag)) {
+    throw new ValidationError('Flag must be a single alphabetic character (example: "q" for "-q").');
+  }
+  return flag;
+}
+
+function parseBooleanStrict(rawValue, fieldName) {
+  const normalized = rawValue.trim().toLowerCase();
+  if (["true", "yes", "y", "1"].includes(normalized)) {
+    return true;
+  }
+  if (["false", "no", "n", "0"].includes(normalized)) {
+    return false;
+  }
+  throw new ValidationError(`${fieldName} must be true/false.`);
+}
+
+function parseIntegerStrict(rawValue, fieldName) {
+  if (!/^-?\d+$/.test(rawValue.trim())) {
+    throw new ValidationError(`${fieldName} must be an integer.`);
+  }
+  return Number.parseInt(rawValue.trim(), 10);
+}
+
+async function askNonEmpty(prompter, question) {
+  while (true) {
+    const answer = await prompter.ask(question);
+    if (answer.length > 0) {
+      return answer;
+    }
+  }
+}
+
+async function askParameterType(prompter) {
+  while (true) {
+    const answer = (await askNonEmpty(prompter, "What type? (string/integer/boolean/single-choice-list): ")).toLowerCase();
+    if (PARAMETER_TYPES.includes(answer)) {
+      return answer;
+    }
+    prompter.write(`Invalid type. Allowed values: ${PARAMETER_TYPES.join(", ")}\n`);
+  }
+}
+
+async function askRequired(prompter) {
+  while (true) {
+    const answer = (await askNonEmpty(prompter, "Is it required? (true/false): ")).toLowerCase();
+    if (answer === "true" || answer === "false") {
+      return answer === "true";
+    }
+    prompter.write("Please answer true or false.\n");
+  }
+}
+
+function parseDefaultValue(rawDefault, type, values) {
+  const trimmed = rawDefault.trim();
+  if (trimmed === "") {
+    return null;
+  }
+
+  switch (type) {
+    case "string":
+      return trimmed;
+    case "integer":
+      return parseIntegerStrict(trimmed, "Default value");
+    case "boolean":
+      return parseBooleanStrict(trimmed, "Default value");
+    case "single-choice-list":
+      if (!values.includes(trimmed)) {
+        throw new ValidationError(`Default value must be one of: ${values.join(", ")}`);
+      }
+      return trimmed;
+    default:
+      return trimmed;
+  }
+}
+
+async function collectParameterDefinition(prompter, parameterKeys, flagsInUse) {
+  const parameterKey = await askNonEmpty(prompter, "What parameter key do you want? (type done to finish): ");
+  if (parameterKey.toLowerCase() === "done") {
+    return null;
+  }
+  if (parameterKeys.has(parameterKey)) {
+    throw new ValidationError(`Parameter "${parameterKey}" already exists for this command.`);
+  }
+
+  const type = await askParameterType(prompter);
+  const rawFlag = await askNonEmpty(prompter, "What flag should be used? (example: q): ");
+  const flag = normalizeFlag(rawFlag);
+  if (flagsInUse.has(flag)) {
+    throw new ValidationError(`Flag "-${flag}" is already in use for this command.`);
+  }
+
+  const required = await askRequired(prompter);
+  const rawDefault = await prompter.ask("Default value? (leave empty for none): ");
+
+  let values = undefined;
+  if (type === "single-choice-list") {
+    const rawValues = await askNonEmpty(prompter, "Enter allowed values (comma separated): ");
+    values = rawValues
+      .split(",")
+      .map((value) => value.trim())
+      .filter(Boolean);
+
+    if (values.length === 0) {
+      throw new ValidationError("Single-choice-list requires at least one allowed value.");
+    }
+  }
+
+  const defaultValue = parseDefaultValue(rawDefault, type, values ?? []);
+  return {
+    parameterKey,
+    parameterDefinition: {
+      type,
+      flag,
+      required,
+      defaultValue,
+      ...(values ? { values } : {}),
+    },
+  };
+}
+
+async function askAddAnotherCommand(prompter) {
+  while (true) {
+    const answer = (await askNonEmpty(prompter, "Do you want to add another command? (yes/no): ")).toLowerCase();
+    if (answer === "yes" || answer === "y") {
+      return true;
+    }
+    if (answer === "no" || answer === "n") {
+      return false;
+    }
+    prompter.write("Please answer yes or no.\n");
+  }
+}
+
+export async function runInitFlow({ config, prompter, saveConfig }) {
+  const updatedConfig = { ...config };
+
+  while (true) {
+    const commandName = await askNonEmpty(
+      prompter,
+      "What command do you want to create? (example: grafana, google, or finish): ",
+    );
+
+    if (commandName.toLowerCase() === "finish") {
+      break;
+    }
+
+    if (updatedConfig[commandName]) {
+      prompter.write(`Command "${commandName}" already exists.\n`);
+      continue;
+    }
+
+    const description = await askNonEmpty(prompter, "What description do you want to add? ");
+    const url = await askNonEmpty(
+      prompter,
+      "What URL template do you want to use? (example: https://grafana.com/{environments}/{query}/{timeframe}) ",
+    );
+
+    const parameterKeys = new Set();
+    const flagsInUse = new Set();
+    const parameters = {};
+
+    while (true) {
+      try {
+        const parameter = await collectParameterDefinition(prompter, parameterKeys, flagsInUse);
+        if (parameter === null) {
+          break;
+        }
+
+        parameterKeys.add(parameter.parameterKey);
+        flagsInUse.add(parameter.parameterDefinition.flag);
+        parameters[parameter.parameterKey] = parameter.parameterDefinition;
+      } catch (error) {
+        prompter.write(`${error.message}\n`);
+      }
+    }
+
+    updatedConfig[commandName] = {
+      description,
+      url,
+      parameters,
+    };
+
+    const addAnother = await askAddAnotherCommand(prompter);
+    if (!addAnother) {
+      break;
+    }
+  }
+
+  await saveConfig(updatedConfig);
+  prompter.write("Configuration updated.\n");
+  return updatedConfig;
+}

package/src/commands/list.mjs

@@ -0,0 +1,10 @@
+export function buildCommandList(config = {}) {
+  const entries = Object.entries(config);
+  if (entries.length === 0) {
+    return "No commands configured yet. Run `launchr init` to add commands.";
+  }
+
+  return entries
+    .map(([name, definition]) => `${name}  - ${definition.description}`)
+    .join("\n");
+}