launchr-cli 1.0.0

package/src/commands/run-custom.mjs

@@ -0,0 +1,24 @@
+import { parseShortFlags } from "../parsing/flags.mjs";
+import { interpolateUrlTemplate } from "../utils/url-template.mjs";
+import { resolveRuntimeParameters } from "../validation/runtime-params.mjs";
+
+export async function runCustomCommand({
+  commandName,
+  commandConfig,
+  argv,
+  openUrl,
+}) {
+  const valuesByFlag = parseShortFlags(argv);
+  const { valuesByParameterKey } = resolveRuntimeParameters(
+    commandName,
+    commandConfig,
+    valuesByFlag,
+  );
+  const finalUrl = interpolateUrlTemplate(commandConfig.url, valuesByParameterKey);
+  await openUrl(finalUrl);
+
+  return {
+    finalUrl,
+    valuesByParameterKey,
+  };
+}

package/src/config/paths.mjs

@@ -0,0 +1,10 @@
+import os from "node:os";
+import path from "node:path";
+
+export function getConfigDirPath(homeDir = os.homedir()) {
+  return path.join(homeDir, ".launchr-configurations");
+}
+
+export function getConfigFilePath(homeDir = os.homedir()) {
+  return path.join(getConfigDirPath(homeDir), "launchr-commands.json");
+}

package/src/config/schema.mjs

@@ -0,0 +1,136 @@
+import { PARAMETER_TYPES } from "../constants.mjs";
+import { ValidationError } from "../utils/errors.mjs";
+import { extractTemplatePlaceholders } from "../utils/url-template.mjs";
+
+export const CONFIG_JSON_SCHEMA = {
+  type: "object",
+  additionalProperties: {
+    type: "object",
+    required: ["description", "url", "parameters"],
+    properties: {
+      description: { type: "string" },
+      url: { type: "string" },
+      parameters: {
+        type: "object",
+        additionalProperties: {
+          type: "object",
+          required: ["type", "flag", "required"],
+          properties: {
+            type: { enum: PARAMETER_TYPES },
+            flag: { type: "string", minLength: 1 },
+            required: { type: "boolean" },
+            defaultValue: {},
+            values: { type: "array" },
+          },
+        },
+      },
+    },
+  },
+};
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function assert(condition, message) {
+  if (!condition) {
+    throw new ValidationError(message);
+  }
+}
+
+function validateFlag(flag, location) {
+  assert(typeof flag === "string" && flag.trim().length > 0, `${location}.flag must be a non-empty string`);
+  const normalized = flag.replace(/^-+/, "").trim();
+  assert(/^[a-zA-Z]$/.test(normalized), `${location}.flag must be a single alphabetic character`);
+}
+
+function validateTemplatePlaceholders(commandName, commandConfig) {
+  const commandLocation = `Command "${commandName}"`;
+  const parameterKeys = Object.keys(commandConfig.parameters);
+  const parameterKeySet = new Set(parameterKeys);
+
+  assert(
+    !commandConfig.url.includes("%s"),
+    `${commandLocation}.url uses deprecated "%s" placeholders. Use named placeholders like {query}.`,
+  );
+
+  const rawPlaceholderTokens = commandConfig.url.match(/{[^}]+}/g) ?? [];
+  for (const rawToken of rawPlaceholderTokens) {
+    const tokenBody = rawToken.slice(1, -1);
+    assert(
+      /^[a-zA-Z0-9_-]+$/.test(tokenBody),
+      `${commandLocation}.url has invalid placeholder ${rawToken}. Use {parameter_key} with letters, numbers, _ or -.`,
+    );
+  }
+
+  const placeholderNames = extractTemplatePlaceholders(commandConfig.url);
+  const placeholderNameSet = new Set(placeholderNames);
+
+  const unknownPlaceholders = [...placeholderNameSet].filter((name) => !parameterKeySet.has(name));
+  assert(
+    unknownPlaceholders.length === 0,
+    `${commandLocation}.url has unknown placeholders: ${unknownPlaceholders.map((name) => `{${name}}`).join(", ")}`,
+  );
+
+  const missingPlaceholders = parameterKeys.filter((key) => !placeholderNameSet.has(key));
+  assert(
+    missingPlaceholders.length === 0,
+    `${commandLocation}.url is missing placeholders for parameters: ${missingPlaceholders.map((name) => `{${name}}`).join(", ")}`,
+  );
+}
+
+function validateSingleCommand(commandName, commandConfig) {
+  const commandLocation = `Command "${commandName}"`;
+  assert(isPlainObject(commandConfig), `${commandLocation} must be an object`);
+  assert(typeof commandConfig.description === "string", `${commandLocation}.description must be a string`);
+  assert(typeof commandConfig.url === "string", `${commandLocation}.url must be a string`);
+  assert(isPlainObject(commandConfig.parameters), `${commandLocation}.parameters must be an object`);
+
+  const seenFlags = new Set();
+
+  for (const [paramName, paramDef] of Object.entries(commandConfig.parameters)) {
+    const parameterLocation = `${commandLocation}.parameters.${paramName}`;
+    assert(isPlainObject(paramDef), `${parameterLocation} must be an object`);
+    assert(typeof paramDef.type === "string", `${parameterLocation}.type must be a string`);
+    assert(PARAMETER_TYPES.includes(paramDef.type), `${parameterLocation}.type must be one of: ${PARAMETER_TYPES.join(", ")}`);
+    validateFlag(paramDef.flag, parameterLocation);
+    assert(typeof paramDef.required === "boolean", `${parameterLocation}.required must be a boolean`);
+
+    const normalizedFlag = paramDef.flag.replace(/^-+/, "");
+    assert(!seenFlags.has(normalizedFlag), `${commandLocation} has duplicated flag "-${normalizedFlag}"`);
+    seenFlags.add(normalizedFlag);
+
+    if (paramDef.type === "single-choice-list") {
+      assert(Array.isArray(paramDef.values), `${parameterLocation}.values must be an array for single-choice-list`);
+      assert(paramDef.values.length > 0, `${parameterLocation}.values must contain at least one value`);
+      for (const value of paramDef.values) {
+        assert(typeof value === "string" && value.length > 0, `${parameterLocation}.values must contain non-empty strings`);
+      }
+      if (paramDef.defaultValue !== undefined && paramDef.defaultValue !== null) {
+        const defaultValue = String(paramDef.defaultValue);
+        assert(paramDef.values.includes(defaultValue), `${parameterLocation}.defaultValue must be one of the allowed values`);
+      }
+    }
+
+    if (paramDef.type === "integer" && paramDef.defaultValue !== undefined && paramDef.defaultValue !== null) {
+      const integerPattern = /^-?\d+$/;
+      assert(integerPattern.test(String(paramDef.defaultValue)), `${parameterLocation}.defaultValue must be an integer`);
+    }
+
+    if (paramDef.type === "boolean" && paramDef.defaultValue !== undefined && paramDef.defaultValue !== null) {
+      const raw = String(paramDef.defaultValue).toLowerCase();
+      const validBoolean = raw === "true" || raw === "false" || raw === "1" || raw === "0";
+      assert(validBoolean, `${parameterLocation}.defaultValue must be a boolean (true/false/1/0)`);
+    }
+  }
+
+  validateTemplatePlaceholders(commandName, commandConfig);
+}
+
+export function validateConfigSchema(config) {
+  assert(isPlainObject(config), "Configuration root must be a JSON object");
+  for (const [commandName, commandConfig] of Object.entries(config)) {
+    validateSingleCommand(commandName, commandConfig);
+  }
+  return config;
+}

package/src/config/store.mjs

@@ -0,0 +1,82 @@
+import { mkdir, readFile, rename, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { CONFIG_PROMPT_TEXT, CONFIG_REQUIRED_MESSAGE } from "../constants.mjs";
+import { ConfigError } from "../utils/errors.mjs";
+import { validateConfigSchema } from "./schema.mjs";
+
+async function pathExists(filePath) {
+  try {
+    await stat(filePath);
+    return true;
+  } catch (error) {
+    if (error && error.code === "ENOENT") {
+      return false;
+    }
+    throw error;
+  }
+}
+
+export async function createEmptyConfiguration(configDirPath, configFilePath) {
+  await mkdir(configDirPath, { recursive: true });
+  await writeFile(configFilePath, "{}\n", "utf8");
+}
+
+export async function ensureConfigExistsOrPromptCreate(options) {
+  const {
+    configDirPath,
+    configFilePath,
+    promptYesNo,
+    promptText = CONFIG_PROMPT_TEXT,
+  } = options;
+
+  const exists = await pathExists(configFilePath);
+  if (exists) {
+    return;
+  }
+
+  const shouldCreate = await promptYesNo(promptText);
+  if (!shouldCreate) {
+    throw new ConfigError(CONFIG_REQUIRED_MESSAGE);
+  }
+
+  await createEmptyConfiguration(configDirPath, configFilePath);
+}
+
+export async function loadConfiguration(configFilePath) {
+  let rawText;
+  try {
+    rawText = await readFile(configFilePath, "utf8");
+  } catch (error) {
+    if (error && error.code === "ENOENT") {
+      throw new ConfigError(`Configuration file not found at ${configFilePath}`);
+    }
+    throw new ConfigError(`Unable to read configuration file at ${configFilePath}`, { cause: error });
+  }
+
+  let parsed;
+  try {
+    parsed = rawText.trim().length === 0 ? {} : JSON.parse(rawText);
+  } catch (error) {
+    throw new ConfigError(`Configuration file is corrupted JSON: ${configFilePath}`, { cause: error });
+  }
+
+  try {
+    return validateConfigSchema(parsed);
+  } catch (error) {
+    if (error instanceof ConfigError) {
+      throw error;
+    }
+    throw new ConfigError(`Configuration schema validation failed: ${error.message}`, { cause: error });
+  }
+}
+
+export async function saveConfiguration(configFilePath, configObject) {
+  validateConfigSchema(configObject);
+  const tempFilePath = path.join(
+    path.dirname(configFilePath),
+    `${path.basename(configFilePath)}.tmp`,
+  );
+  const payload = `${JSON.stringify(configObject, null, 2)}\n`;
+  await writeFile(tempFilePath, payload, "utf8");
+  await rename(tempFilePath, configFilePath);
+}

package/src/constants.mjs

@@ -0,0 +1,14 @@
+export const BUILTIN_COMMANDS = ["help", "list", "init"];
+
+export const PARAMETER_TYPES = [
+  "string",
+  "integer",
+  "boolean",
+  "single-choice-list",
+];
+
+export const CONFIG_PROMPT_TEXT =
+  "No configuration found. Do you want to create one? (yes/no)";
+
+export const CONFIG_REQUIRED_MESSAGE =
+  "Configuration file is required to use this CLI.";

package/src/parsing/argv.mjs

@@ -0,0 +1,7 @@
+export function parseArgv(argv) {
+  const safeArgv = Array.isArray(argv) ? argv : [];
+  return {
+    command: safeArgv[0] ?? null,
+    rest: safeArgv.slice(1),
+  };
+}

package/src/parsing/flags.mjs

@@ -0,0 +1,33 @@
+import { UsageError } from "../utils/errors.mjs";
+
+function isFlagToken(token) {
+  return typeof token === "string" && /^-[a-zA-Z]$/.test(token);
+}
+
+export function parseShortFlags(tokens) {
+  const providedTokens = Array.isArray(tokens) ? tokens : [];
+  const valuesByFlag = new Map();
+
+  for (let index = 0; index < providedTokens.length; index += 1) {
+    const token = providedTokens[index];
+    if (!isFlagToken(token)) {
+      throw new UsageError(`Unexpected token: "${token}". Only short flags like -q are supported.`);
+    }
+
+    const flag = token.slice(1);
+    if (valuesByFlag.has(flag)) {
+      throw new UsageError(`Flag "-${flag}" was provided more than once.`);
+    }
+
+    const nextToken = providedTokens[index + 1];
+    if (nextToken === undefined || isFlagToken(nextToken)) {
+      valuesByFlag.set(flag, true);
+      continue;
+    }
+
+    valuesByFlag.set(flag, nextToken);
+    index += 1;
+  }
+
+  return valuesByFlag;
+}

package/src/utils/browser.mjs

@@ -0,0 +1,69 @@
+import process from "node:process";
+import { ValidationError } from "./errors.mjs";
+
+const SPECIAL_SCHEMES = ["mailto:", "tel:", "sms:", "data:"];
+
+function hasExplicitScheme(value) {
+  return value.includes("://") || SPECIAL_SCHEMES.some((scheme) => value.toLowerCase().startsWith(scheme));
+}
+
+export function normalizeUrlTarget(rawUrl) {
+  const value = String(rawUrl ?? "").trim();
+
+  if (value.length === 0) {
+    throw new ValidationError("URL is empty after interpolation.");
+  }
+
+  if (value.startsWith("//")) {
+    return `https:${value}`;
+  }
+
+  if (hasExplicitScheme(value)) {
+    return value;
+  }
+
+  return `https://${value}`;
+}
+
+export function assertValidAbsoluteUrl(url) {
+  try {
+    // URL constructor enforces absolute URL validity.
+    // Relative or malformed targets should fail fast with a clear error.
+    new URL(url);
+  } catch {
+    throw new ValidationError(`Invalid URL: ${url}`);
+  }
+}
+
+async function runWithZx(command, url) {
+  const { $ } = await import("zx");
+  if (command === "open") {
+    await $`open ${url}`;
+    return;
+  }
+  if (command === "cmd") {
+    await $`cmd /c start "" ${url}`;
+    return;
+  }
+  await $`xdg-open ${url}`;
+}
+
+export async function openInBrowser(url, options = {}) {
+  const platform = options.platform ?? process.platform;
+  const runCommand = options.runCommand ?? runWithZx;
+
+  const normalizedUrl = normalizeUrlTarget(url);
+  assertValidAbsoluteUrl(normalizedUrl);
+
+  if (platform === "darwin") {
+    await runCommand("open", normalizedUrl);
+    return;
+  }
+
+  if (platform === "win32") {
+    await runCommand("cmd", normalizedUrl);
+    return;
+  }
+
+  await runCommand("xdg-open", normalizedUrl);
+}

package/src/utils/errors.mjs

@@ -0,0 +1,26 @@
+export class AppError extends Error {
+  constructor(message, options = {}) {
+    super(message);
+    this.name = this.constructor.name;
+    this.code = options.code ?? "APP_ERROR";
+    this.cause = options.cause;
+  }
+}
+
+export class UsageError extends AppError {
+  constructor(message, options = {}) {
+    super(message, { ...options, code: options.code ?? "USAGE_ERROR" });
+  }
+}
+
+export class ConfigError extends AppError {
+  constructor(message, options = {}) {
+    super(message, { ...options, code: options.code ?? "CONFIG_ERROR" });
+  }
+}
+
+export class ValidationError extends AppError {
+  constructor(message, options = {}) {
+    super(message, { ...options, code: options.code ?? "VALIDATION_ERROR" });
+  }
+}

package/src/utils/prompt.mjs

@@ -0,0 +1,55 @@
+import { createInterface } from "node:readline/promises";
+import { stdin as defaultInput, stdout as defaultOutput } from "node:process";
+import { ValidationError } from "./errors.mjs";
+
+export function createPrompter(options = {}) {
+  const input = options.input ?? defaultInput;
+  const output = options.output ?? defaultOutput;
+  const rl = createInterface({ input, output });
+
+  let isClosed = false;
+
+  return {
+    async ask(question) {
+      if (isClosed) {
+        throw new ValidationError("Prompt session is closed");
+      }
+      try {
+        const answer = await rl.question(question);
+        return answer.trim();
+      } catch (error) {
+        throw new ValidationError("Prompt interrupted");
+      }
+    },
+    close() {
+      if (!isClosed) {
+        isClosed = true;
+        rl.close();
+      }
+    },
+    write(text) {
+      output.write(text);
+    },
+  };
+}
+
+export async function promptYesNo(question, options = {}) {
+  const prompter = createPrompter(options);
+  try {
+    while (true) {
+      const answer = (await prompter.ask(`${question} `)).toLowerCase();
+      if (answer === "yes" || answer === "y") {
+        return true;
+      }
+      if (answer === "no" || answer === "n") {
+        return false;
+      }
+      if (answer === "") {
+        continue;
+      }
+      options.output?.write?.("Please answer yes or no.\n");
+    }
+  } finally {
+    prompter.close();
+  }
+}

package/src/utils/url-template.mjs

@@ -0,0 +1,36 @@
+import { ValidationError } from "./errors.mjs";
+
+const PLACEHOLDER_PATTERN = /{([a-zA-Z0-9_-]+)}/g;
+
+export function extractTemplatePlaceholders(template) {
+  const text = String(template);
+  const placeholders = [];
+
+  PLACEHOLDER_PATTERN.lastIndex = 0;
+  let match = PLACEHOLDER_PATTERN.exec(text);
+  while (match !== null) {
+    placeholders.push(match[1]);
+    match = PLACEHOLDER_PATTERN.exec(text);
+  }
+
+  return placeholders;
+}
+
+function hasOwnKey(record, key) {
+  return Object.prototype.hasOwnProperty.call(record, key);
+}
+
+function encodeTemplateValue(value) {
+  return encodeURIComponent(String(value));
+}
+
+export function interpolateUrlTemplate(template, valuesByParameterKey) {
+  const text = String(template);
+  return text.replace(PLACEHOLDER_PATTERN, (fullMatch, parameterKey) => {
+    if (!hasOwnKey(valuesByParameterKey, parameterKey)) {
+      throw new ValidationError(`URL placeholder "{${parameterKey}}" has no matching parameter value.`);
+    }
+
+    return encodeTemplateValue(valuesByParameterKey[parameterKey]);
+  });
+}

package/src/validation/runtime-params.mjs

@@ -0,0 +1,95 @@
+import { ValidationError } from "../utils/errors.mjs";
+
+function parseInteger(rawValue, paramKey) {
+  const normalized = String(rawValue);
+  if (!/^-?\d+$/.test(normalized)) {
+    throw new ValidationError(`Parameter "${paramKey}" must be an integer.`);
+  }
+  return Number.parseInt(normalized, 10);
+}
+
+function parseBoolean(rawValue, paramKey) {
+  if (typeof rawValue === "boolean") {
+    return rawValue;
+  }
+
+  const normalized = String(rawValue).toLowerCase();
+  if (normalized === "true" || normalized === "1" || normalized === "yes" || normalized === "y") {
+    return true;
+  }
+  if (normalized === "false" || normalized === "0" || normalized === "no" || normalized === "n") {
+    return false;
+  }
+
+  throw new ValidationError(`Parameter "${paramKey}" must be boolean (true/false).`);
+}
+
+function normalizeValueByType(rawValue, parameterKey, parameterDefinition) {
+  switch (parameterDefinition.type) {
+    case "string":
+      return String(rawValue);
+    case "integer":
+      return parseInteger(rawValue, parameterKey);
+    case "boolean":
+      return parseBoolean(rawValue, parameterKey);
+    case "single-choice-list": {
+      const stringValue = String(rawValue);
+      if (!parameterDefinition.values.includes(stringValue)) {
+        throw new ValidationError(
+          `Parameter "${parameterKey}" must be one of: ${parameterDefinition.values.join(", ")}`,
+        );
+      }
+      return stringValue;
+    }
+    default:
+      throw new ValidationError(`Unsupported parameter type: ${parameterDefinition.type}`);
+  }
+}
+
+function hasUsableDefault(definition) {
+  return definition.defaultValue !== undefined && definition.defaultValue !== null && definition.defaultValue !== "";
+}
+
+export function resolveRuntimeParameters(commandName, commandConfig, valuesByFlag) {
+  const parameterEntries = Object.entries(commandConfig.parameters);
+  const allowedFlags = new Set(parameterEntries.map(([, definition]) => definition.flag.replace(/^-+/, "")));
+
+  for (const incomingFlag of valuesByFlag.keys()) {
+    if (!allowedFlags.has(incomingFlag)) {
+      throw new ValidationError(`Unknown flag "-${incomingFlag}" for command "${commandName}".`);
+    }
+  }
+
+  const valuesInOrder = [];
+  const valuesByParameterKey = {};
+
+  for (const [parameterKey, definition] of parameterEntries) {
+    const normalizedFlag = definition.flag.replace(/^-+/, "");
+    let rawValue = valuesByFlag.get(normalizedFlag);
+
+    if (rawValue === true && definition.type !== "boolean") {
+      throw new ValidationError(`Flag "-${normalizedFlag}" requires a value.`);
+    }
+
+    if (rawValue === undefined) {
+      if (hasUsableDefault(definition)) {
+        rawValue = definition.defaultValue;
+      } else if (definition.required) {
+        throw new ValidationError(`Missing required parameter "${parameterKey}" (-${normalizedFlag}).`);
+      } else {
+        valuesByParameterKey[parameterKey] = "";
+        valuesInOrder.push("");
+        continue;
+      }
+    }
+
+    const normalizedValue = normalizeValueByType(rawValue, parameterKey, definition);
+    valuesByParameterKey[parameterKey] = normalizedValue;
+    valuesInOrder.push(normalizedValue);
+  }
+
+  return {
+    valuesInOrder,
+    valuesByParameterKey,
+  };
+}

package/test/browser.test.mjs

@@ -0,0 +1,39 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import {
+  normalizeUrlTarget,
+  assertValidAbsoluteUrl,
+  openInBrowser,
+} from "../src/utils/browser.mjs";
+
+test("normalizeUrlTarget adds https to scheme-less host paths", () => {
+  assert.equal(normalizeUrlTarget("test.com/asd"), "https://test.com/asd");
+  assert.equal(normalizeUrlTarget("localhost:3000/docs"), "https://localhost:3000/docs");
+});
+
+test("normalizeUrlTarget preserves explicit schemes", () => {
+  assert.equal(normalizeUrlTarget("https://test.com/asd"), "https://test.com/asd");
+  assert.equal(normalizeUrlTarget("mailto:user@example.com"), "mailto:user@example.com");
+  assert.equal(normalizeUrlTarget("//cdn.example.com/lib.js"), "https://cdn.example.com/lib.js");
+});
+
+test("normalizeUrlTarget rejects empty input", () => {
+  assert.throws(() => normalizeUrlTarget("   "), /URL is empty/);
+});
+
+test("assertValidAbsoluteUrl rejects malformed URLs", () => {
+  assert.throws(() => assertValidAbsoluteUrl("http://"), /Invalid URL/);
+});
+
+test("openInBrowser invokes platform opener with normalized URL", async () => {
+  const calls = [];
+
+  await openInBrowser("test.com/asd", {
+    platform: "darwin",
+    runCommand: async (command, url) => {
+      calls.push({ command, url });
+    },
+  });
+
+  assert.deepEqual(calls, [{ command: "open", url: "https://test.com/asd" }]);
+});