@boneskull/bargs 0.1.1

package/dist/version.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Package version and metadata detection utilities.
+ *
+ * Provides functions to locate and read `package.json` files by walking up the
+ * directory tree, extracting version strings, and gathering package metadata
+ * (homepage, repository URLs) for automatic epilog generation in help output.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Package info extracted from `package.json` for epilog generation.
+ */
+interface PackageInfo {
+    homepage?: string;
+    repository?: string;
+}
+/**
+ * Detect version: use provided version or read from nearest package.json.
+ */
+export declare const detectVersion: (providedVersion: string | undefined, startDir?: string) => Promise<string | undefined>;
+/**
+ * Read package info (homepage, repository) from package.json synchronously.
+ * Returns only HTTPS URLs; other URL schemes are omitted.
+ */
+export declare const readPackageInfoSync: (startDir?: string) => PackageInfo;
+export {};
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH;;GAEG;AACH,UAAU,WAAW;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAqHD;;GAEG;AACH,eAAO,MAAM,aAAa,GACxB,iBAAiB,MAAM,GAAG,SAAS,EACnC,WAAU,MAAsB,KAC/B,OAAO,CAAC,MAAM,GAAG,SAAS,CAW5B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,mBAAmB,GAC9B,WAAU,MAAsB,KAC/B,WAiBF,CAAC"}

package/dist/version.js

@@ -0,0 +1,129 @@
+/**
+ * Package version and metadata detection utilities.
+ *
+ * Provides functions to locate and read `package.json` files by walking up the
+ * directory tree, extracting version strings, and gathering package metadata
+ * (homepage, repository URLs) for automatic epilog generation in help output.
+ *
+ * @packageDocumentation
+ */
+import { readFileSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+/**
+ * Normalize a repository URL to clean HTTPS format. Strips leading `git+` and
+ * trailing `.git`.
+ */
+const normalizeRepoUrl = (url) => {
+    return url.replace(/^git\+/, '').replace(/\.git$/, '');
+};
+/**
+ * Validate that a URL is HTTPS. Returns the URL if valid, undefined otherwise.
+ */
+const validateHttpsUrl = (url) => {
+    if (!url) {
+        return undefined;
+    }
+    return url.startsWith('https://') ? url : undefined;
+};
+/**
+ * Extract repository URL from package.json repository field. Handles both
+ * string and object forms.
+ */
+const extractRepoUrl = (repository) => {
+    if (!repository) {
+        return undefined;
+    }
+    const rawUrl = typeof repository === 'string' ? repository : repository.url;
+    if (!rawUrl) {
+        return undefined;
+    }
+    const normalized = normalizeRepoUrl(rawUrl);
+    return validateHttpsUrl(normalized);
+};
+/**
+ * Find package.json by walking up from startDir (async).
+ */
+const findPackageJson = async (startDir) => {
+    let dir = startDir;
+    let prevDir = '';
+    while (dir !== prevDir) {
+        const pkgPath = join(dir, 'package.json');
+        try {
+            await readFile(pkgPath, 'utf-8');
+            return pkgPath;
+        }
+        catch {
+            prevDir = dir;
+            dir = dirname(dir);
+        }
+    }
+    return undefined;
+};
+/**
+ * Find package.json by walking up from startDir (sync).
+ */
+const findPackageJsonSync = (startDir) => {
+    let dir = startDir;
+    let prevDir = '';
+    while (dir !== prevDir) {
+        const pkgPath = join(dir, 'package.json');
+        try {
+            readFileSync(pkgPath, 'utf-8');
+            return pkgPath;
+        }
+        catch {
+            prevDir = dir;
+            dir = dirname(dir);
+        }
+    }
+    return undefined;
+};
+/**
+ * Read version from package.json (async).
+ */
+const readVersionFromPackageJson = async (pkgPath) => {
+    try {
+        const content = await readFile(pkgPath, 'utf-8');
+        const pkg = JSON.parse(content);
+        return pkg.version;
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * Detect version: use provided version or read from nearest package.json.
+ */
+export const detectVersion = async (providedVersion, startDir = process.cwd()) => {
+    if (providedVersion) {
+        return providedVersion;
+    }
+    const pkgPath = await findPackageJson(startDir);
+    if (!pkgPath) {
+        return undefined;
+    }
+    return readVersionFromPackageJson(pkgPath);
+};
+/**
+ * Read package info (homepage, repository) from package.json synchronously.
+ * Returns only HTTPS URLs; other URL schemes are omitted.
+ */
+export const readPackageInfoSync = (startDir = process.cwd()) => {
+    const pkgPath = findPackageJsonSync(startDir);
+    if (!pkgPath) {
+        return {};
+    }
+    try {
+        const content = readFileSync(pkgPath, 'utf-8');
+        const pkg = JSON.parse(content);
+        return {
+            homepage: validateHttpsUrl(pkg.homepage),
+            repository: extractRepoUrl(pkg.repository),
+        };
+    }
+    catch {
+        return {};
+    }
+};
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,149 @@
+{
+  "name": "@boneskull/bargs",
+  "version": "0.1.1",
+  "type": "module",
+  "description": "A TypeScript-first CLI argument parser wrapping util.parseArgs() with full type inference",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/boneskull/bargs.git"
+  },
+  "homepage": "https://github.com/boneskull/bargs",
+  "author": "Christopher Hiller <boneskull@boneskull.com> (https://boneskull.com/)",
+  "license": "BlueOak-1.0.0",
+  "private": false,
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.cts",
+  "module": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.cts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "cli",
+    "args",
+    "arguments",
+    "parser",
+    "typescript",
+    "terminal",
+    "options",
+    "parseArgs"
+  ],
+  "scripts": {
+    "build": "zshy",
+    "commitlint": "commitlint",
+    "docs": "typedoc",
+    "fix": "run-s -sl fix:*",
+    "fix:eslint": "eslint --fix .",
+    "fix:markdown": "markdownlint-cli2 --fix \"**/*.md\"",
+    "fix:pkg": "npm pkg fix",
+    "fix:prettier": "prettier --write . && markdownlint-cli2 --fix \"**/*.md\"",
+    "lint": "run-p -sl --aggregate-output lint:*",
+    "lint-staged": "lint-staged",
+    "lint:eslint": "eslint .",
+    "lint:knip": "knip",
+    "lint:markdown": "markdownlint-cli2 \"**/*.md\"",
+    "lint:prettier": "prettier --check .",
+    "lint:spelling": "cspell . \"./.*/**\"",
+    "lint:types": "tsc --noEmit",
+    "prepare": "husky; run-s -s build",
+    "test": "run-s test:runtime",
+    "test:runtime": "node --import tsx --test --test-reporter=spec \"test/**/*.test.ts\"",
+    "test:watch": "node --import tsx --test --test-reporter=spec --watch \"test/**/*.test.ts\""
+  },
+  "devDependencies": {
+    "@commitlint/cli": "20.2.0",
+    "@commitlint/config-conventional": "20.2.0",
+    "@eslint/js": "9.39.2",
+    "@stylistic/eslint-plugin": "5.6.1",
+    "@types/node": "24.10.4",
+    "@types/wallabyjs": "0.0.15",
+    "bupkis": "0.14.0",
+    "cspell": "9.4.0",
+    "eslint": "9.39.2",
+    "eslint-plugin-jsonc": "2.21.0",
+    "eslint-plugin-perfectionist": "5.0.0",
+    "globals": "16.5.0",
+    "husky": "9.1.7",
+    "knip": "5.76.1",
+    "lint-staged": "16.2.7",
+    "markdownlint-cli2": "0.20.0",
+    "markdownlint-cli2-formatter-pretty": "0.0.9",
+    "npm-run-all2": "8.0.4",
+    "prettier": "3.7.4",
+    "prettier-plugin-jsdoc": "1.8.0",
+    "prettier-plugin-pkg": "0.21.2",
+    "prettier-plugin-sort-json": "4.1.1",
+    "tsx": "4.21.0",
+    "typedoc": "0.28.15",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.50.0",
+    "zshy": "0.6.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "knip": {
+    "ignoreDependencies": [
+      "markdownlint-cli2-formatter-pretty"
+    ],
+    "ignore": [
+      "**/*.d.ts",
+      ".worktrees/**/*",
+      "examples/**/*"
+    ],
+    "tags": [
+      "-knipignore"
+    ],
+    "node": {
+      "entry": [
+        "src/index.ts",
+        ".wallaby.js",
+        "test/**/*.test.ts"
+      ]
+    }
+  },
+  "lint-staged": {
+    "*.{ts,js,yml,json5}": [
+      "eslint --fix",
+      "prettier --write",
+      "cspell lint --no-must-find-files"
+    ],
+    "**/!(package-lock).json": [
+      "eslint --fix",
+      "prettier --write",
+      "cspell lint --no-must-find-files"
+    ],
+    "*.md": [
+      "markdownlint-cli2 --fix",
+      "prettier --write",
+      "cspell lint --no-must-find-files"
+    ]
+  },
+  "prettier": {
+    "jsdocCommentLineStrategy": "keep",
+    "jsdocPreferCodeFences": true,
+    "plugins": [
+      "prettier-plugin-jsdoc",
+      "prettier-plugin-pkg",
+      "prettier-plugin-sort-json"
+    ],
+    "singleQuote": true,
+    "tsdoc": true
+  },
+  "zshy": {
+    "exports": {
+      ".": "./src/index.ts",
+      "./package.json": "./package.json"
+    }
+  }
+}