@lpm-registry/cli 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -2,12 +2,41 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.2.1] - 2026-03-12
+
+### Added
+
+- **Swift & XCFramework ecosystem support** — quality checks, packaging, framework detection, and local package management for Apple platforms
+- **OIDC token exchange** for secret-free publishing from CI/CD (GitHub Actions, GitLab CI)
+- **Agent Skills management** — `lpm skills` commands for creating and managing `.lpm/skills/` packages
+- `lpm remove` command for uninstalling packages
+- `lpm install --json` output mode for programmatic usage
+- `lpm search` now supports semantic queries
+- Intellisense coverage and XCFramework size checks in quality scoring
+- Node.js type definitions check in quality scoring
+- Graceful HTTP server shutdown after login callback
+
+### Changed
+
+- Updated quality scoring metrics (28 checks for JS, 25 for Swift, 21 for XCFramework)
+- Removed CI config references from quality checks
+- Simplified `getDefaultPath` internals
+- Removed `applyTemplateVariables` logic from config and commands
+- Improved MCP setup command with server config resolution
+- General code structure refactoring for readability
+
+### Fixed
+
+- Error handling for invalid JSON in `package.json`
+- API request handling improvements
+
 ## [0.2.0] - 2025-02-14
 
 ### Added
+
 - Quality scoring system with 27 checks across 4 categories
 - `lpm publish --check` and `--min-score` flags for quality gating
-- `lpm add` command for shadcn-style source code delivery
+- `lpm add` command for source code delivery
 - `lpm.config.json` support for configurable source packages
 - Secure credential storage (OS keychain with encrypted file fallback)
 - SRI integrity verification for package tarballs
@@ -15,11 +44,12 @@ All notable changes to this project will be documented in this file.
 - Exponential backoff retry with rate-limit handling
 
 ### Changed
+
 - Migrated from `node-fetch` to native `fetch` (Node 18+)
 - Removed unused `figlet` and `form-data` dependencies
-- Updated default registry URL to `https://lpm.dev`
 
 ### Fixed
+
 - Missing `await` on `setToken()` in token-rotate command
 - URL construction for `@lpm.dev/owner.pkg` format in open command
 - Inconsistent limit field names in doctor command
@@ -27,6 +57,7 @@ All notable changes to this project will be documented in this file.
 ## [0.1.0] - 2024-12-01
 
 ### Added
+
 - Initial CLI release
 - `lpm login`, `lpm logout`, `lpm whoami` authentication commands
 - `lpm publish`, `lpm install` package management

package/README.md

@@ -12,13 +12,13 @@ npm install -g @lpm-registry/cli
 
 LPM provides convenient aliases for common commands:
 
-| Shortcut | Full Command | Description |
-|----------|--------------|-------------|
-| `lpm i` | `lpm install` | Install packages |
-| `lpm p` | `lpm publish` | Publish package |
-| `lpm l` | `lpm login` | Log in |
-| `lpm lo` | `lpm logout` | Log out |
-| `lpm set <key> <value>` | `lpm config set` | Set config |
+| Shortcut                | Full Command     | Description      |
+| ----------------------- | ---------------- | ---------------- |
+| `lpm i`                 | `lpm install`    | Install packages |
+| `lpm p`                 | `lpm publish`    | Publish package  |
+| `lpm l`                 | `lpm login`      | Log in           |
+| `lpm lo`                | `lpm logout`     | Log out          |
+| `lpm set <key> <value>` | `lpm config set` | Set config       |
 
 ## Package Name Format
 
@@ -29,6 +29,7 @@ LPM uses the `@lpm.dev` scope for all packages with dot notation:
 ```
 
 Examples:
+
 - `@lpm.dev/tolgaergin.my-utils` (personal package)
 - `@lpm.dev/acme-corp.design-system` (org package)
 
@@ -103,10 +104,10 @@ lpm publish --min-score 80     # Block publish if quality score < 80
 lpm publish --check --min-score 90  # Check only, fail if below 90 (useful in CI)
 ```
 
-| Option | Description |
-|--------|-------------|
-| `--check` | Run quality checks and display report, then exit without publishing |
-| `--min-score <n>` | Set minimum quality score (0-100) required to publish |
+| Option            | Description                                                         |
+| ----------------- | ------------------------------------------------------------------- |
+| `--check`         | Run quality checks and display report, then exit without publishing |
+| `--min-score <n>` | Set minimum quality score (0-100) required to publish               |
 
 > **Note:** If `.lpm/skills/` exists in your package but skills aren't included in the tarball, the CLI warns you to add `.lpm` to the `files` field in package.json.
 
@@ -124,13 +125,13 @@ lpm i                       # Shortcut
 
 Agent Skills are fetched by default for packages that include them.
 
-| Option | Description |
-|--------|-------------|
+| Option        | Description                              |
+| ------------- | ---------------------------------------- |
 | `--no-skills` | Skip fetching Agent Skills after install |
 
 #### Add (Source Code)
 
-Download and extract package source code directly into your project (shadcn-style).
+Download and extract package source code directly into your project.
 
 ```bash
 # JavaScript
@@ -196,15 +197,19 @@ lpm quality @lpm.dev/owner.package --json
 Manage Agent Skills for AI coding assistants.
 
 #### `lpm skills validate`
+
 Validate `.lpm/skills/*.md` files in the current directory. Checks file format, frontmatter, content, size limits, and blocked patterns. Shows quality score impact.
 
 #### `lpm skills install [package]`
+
 Fetch and install skills from the registry. Without a package argument, installs skills for all `@lpm.dev/*` dependencies in package.json. Saves to `.lpm/skills/{package-name}/` and adds `.lpm/skills/` to `.gitignore`.
 
 #### `lpm skills list`
+
 List available skills for all installed `@lpm.dev/*` packages. Shows which packages have skills, how many, and whether they're installed locally.
 
 #### `lpm skills clean`
+
 Remove the `.lpm/skills/` directory and all locally installed skills.
 
 ### Security & Maintenance
@@ -335,49 +340,49 @@ import {
   runQualityChecks,
   parseLpmPackageReference,
   detectFramework,
-} from "@lpm-registry/cli"
+} from "@lpm-registry/cli";
 ```
 
 ### Integrity
 
-| Function | Description |
-|----------|-------------|
-| `generateIntegrity(buffer, algorithm?)` | Generate an SRI integrity hash (default: `sha512`) |
-| `verifyIntegrity(buffer, expected)` | Verify a buffer against an SRI integrity string |
-| `verifyIntegrityMultiple(buffer, integrities)` | Verify against multiple integrity strings |
-| `parseIntegrity(integrity)` | Parse an SRI string into `{ algorithm, digest }` |
+| Function                                       | Description                                        |
+| ---------------------------------------------- | -------------------------------------------------- |
+| `generateIntegrity(buffer, algorithm?)`        | Generate an SRI integrity hash (default: `sha512`) |
+| `verifyIntegrity(buffer, expected)`            | Verify a buffer against an SRI integrity string    |
+| `verifyIntegrityMultiple(buffer, integrities)` | Verify against multiple integrity strings          |
+| `parseIntegrity(integrity)`                    | Parse an SRI string into `{ algorithm, digest }`   |
 
 ### Path Safety
 
-| Function | Description |
-|----------|-------------|
-| `validateComponentPath(root, path)` | Validate a component install path stays within project |
-| `validateTarballPaths(extractDir, paths)` | Check tarball entries for path traversal attacks |
-| `resolveSafePath(base, user)` | Safely resolve a user-provided path |
-| `sanitizeFilename(name)` | Strip dangerous characters from a filename |
+| Function                                  | Description                                            |
+| ----------------------------------------- | ------------------------------------------------------ |
+| `validateComponentPath(root, path)`       | Validate a component install path stays within project |
+| `validateTarballPaths(extractDir, paths)` | Check tarball entries for path traversal attacks       |
+| `resolveSafePath(base, user)`             | Safely resolve a user-provided path                    |
+| `sanitizeFilename(name)`                  | Strip dangerous characters from a filename             |
 
 ### Quality
 
-| Function | Description |
-|----------|-------------|
+| Function                                                                    | Description                                                  |
+| --------------------------------------------------------------------------- | ------------------------------------------------------------ |
 | `runQualityChecks({ packageJson, readme, lpmConfig, files, unpackedSize })` | Run all 28 quality checks and return score, checks, and tier |
 
 ### Package Config
 
-| Function | Description |
-|----------|-------------|
-| `parseLpmPackageReference(ref)` | Parse `@lpm.dev/owner.pkg@version?key=val` into components |
-| `readLpmConfig(dir)` | Read and validate `lpm.config.json` from a directory |
-| `validateLpmConfig(config)` | Validate a parsed config object |
-| `filterFiles(files, config, params)` | Filter file rules based on config conditions |
+| Function                             | Description                                                |
+| ------------------------------------ | ---------------------------------------------------------- |
+| `parseLpmPackageReference(ref)`      | Parse `@lpm.dev/owner.pkg@version?key=val` into components |
+| `readLpmConfig(dir)`                 | Read and validate `lpm.config.json` from a directory       |
+| `validateLpmConfig(config)`          | Validate a parsed config object                            |
+| `filterFiles(files, config, params)` | Filter file rules based on config conditions               |
 
 ### Project Utils
 
-| Function | Description |
-|----------|-------------|
-| `detectFramework()` | Detect the project framework (nextjs, vite, remix, astro) |
-| `getDefaultPath(framework, name)` | Get the default component install path for a framework |
-| `getUserImportPrefix()` | Get the user's import alias prefix (e.g. `@/`, `~/`) |
+| Function                          | Description                                               |
+| --------------------------------- | --------------------------------------------------------- |
+| `detectFramework()`               | Detect the project framework (nextjs, vite, remix, astro) |
+| `getDefaultPath(framework, name)` | Get the default component install path for a framework    |
+| `getUserImportPrefix()`           | Get the user's import alias prefix (e.g. `@/`, `~/`)      |
 
 ## Security
 

package/bin/lpm.js

@@ -103,6 +103,14 @@ program
 		"--min-score <score>",
 		"Minimum quality score required to publish (0-100)",
 	)
+	.option(
+		"--provenance",
+		"Force OIDC token exchange for secret-free publishing (auto-detected in GitHub Actions with id-token: write)",
+	)
+	.option(
+		"--dry-run",
+		"Validate and preview the publish (files, size, OIDC status) without uploading",
+	)
 	.action(publish)
 
 program

package/lib/commands/publish.js

@@ -5,7 +5,11 @@ import path from "node:path"
 import { promisify } from "node:util"
 import * as p from "@clack/prompts"
 import { request, verifyTokenScope } from "../api.js"
-import { getRegistryUrl } from "../config.js"
+import {
+	clearTransientToken,
+	getRegistryUrl,
+	setTransientToken,
+} from "../config.js"
 import { SUCCESS_MESSAGES, WARNING_MESSAGES } from "../constants.js"
 import {
 	createEcosystemTarball,
@@ -15,6 +19,12 @@ import {
 	readSwiftManifest,
 } from "../ecosystem.js"
 import { generateIntegrity } from "../integrity.js"
+import {
+	exchangeGitLabOidcToken,
+	exchangeOidcToken,
+	isGitHubActionsWithOidc,
+	isGitLabCiWithOidc,
+} from "../oidc.js"
 import { displayQualityReport } from "../quality/display.js"
 import { runQualityChecks } from "../quality/score.js"
 import { createSpinner, log, printHeader } from "../ui.js"
@@ -300,7 +310,9 @@ async function packWithTar(ecosystem, name, version) {
 
 export async function publish(options = {}) {
 	const checkOnly = !!options.check
+	const dryRun = !!options.dryRun
 	const minScore = options.minScore ? parseInt(options.minScore, 10) : null
+	const forceProvenance = !!options.provenance
 
 	printHeader()
 
@@ -469,6 +481,41 @@ export async function publish(options = {}) {
 		spinner.stop()
 		displayQualityReport(qualityResult)
 
+		// --dry-run: print summary and exit without uploading
+		if (dryRun) {
+			const unpackedSize = npmPackMeta.unpackedSize || 0
+			const fileCount =
+				npmPackMeta.fileCount || (npmPackMeta.files?.length ?? 0)
+			const sizeStr =
+				unpackedSize >= 1024 * 1024
+					? `${(unpackedSize / 1024 / 1024).toFixed(1)} MB unpacked`
+					: `${(unpackedSize / 1024).toFixed(1)} kB unpacked`
+
+			const githubOidc = isGitHubActionsWithOidc()
+			const gitlabOidc = isGitLabCiWithOidc()
+			const oidcStr = githubOidc
+				? "GitHub Actions detected ✓"
+				: gitlabOidc
+					? "GitLab CI detected ✓"
+					: "Not running in CI"
+			const authStr =
+				githubOidc || gitlabOidc
+					? "Token will be exchanged at publish time"
+					: "Run lpm login or configure Trusted Publishers"
+
+			console.log("")
+			console.log(`  Package  ${name}`)
+			console.log(`  Version  ${version}`)
+			console.log(`  Files    ${fileCount} files`)
+			console.log(`  Size     ${sizeStr}`)
+			console.log("")
+			console.log(`  OIDC     ${oidcStr}`)
+			console.log(`  Auth     ${authStr}`)
+			console.log("")
+			log.info("Dry run complete — run without --dry-run to publish.")
+			process.exit(0)
+		}
+
 		// --check mode: display report and exit
 		if (checkOnly) {
 			if (minScore && qualityResult.score < minScore) {
@@ -500,6 +547,50 @@ export async function publish(options = {}) {
 			process.exit(0)
 		}
 
+		// 8.5. OIDC auto-detection: exchange a GitHub Actions or GitLab CI OIDC
+		// token for a short-lived LPM publish token. Runs before auth verification
+		// so that verifyTokenScope() picks up the OIDC token via getToken().
+		const githubOidcAvailable = isGitHubActionsWithOidc()
+		const gitlabOidcAvailable = isGitLabCiWithOidc()
+		const oidcAvailable = githubOidcAvailable || gitlabOidcAvailable
+
+		if (forceProvenance && !oidcAvailable) {
+			p.cancel(
+				"--provenance requires OIDC to be available. " +
+					"For GitHub Actions, ensure `id-token: write` permission. " +
+					"For GitLab CI, configure id_tokens in your job.",
+			)
+			process.exit(1)
+		}
+		if (oidcAvailable) {
+			spinner.start()
+			if (githubOidcAvailable) {
+				spinner.text = "Requesting OIDC token from GitHub Actions..."
+			} else {
+				spinner.text = "Exchanging GitLab CI OIDC token..."
+			}
+			try {
+				const oidcToken = githubOidcAvailable
+					? await exchangeOidcToken(name)
+					: await exchangeGitLabOidcToken(name)
+				setTransientToken(oidcToken)
+				spinner.stop()
+				const provider = githubOidcAvailable ? "GitHub Actions" : "GitLab CI"
+				log.success(
+					`OIDC authentication successful (${provider} — no secrets needed)`,
+				)
+			} catch (err) {
+				spinner.stop()
+				if (forceProvenance) {
+					// When --provenance is explicit, a failure is fatal
+					throw new Error(`OIDC exchange failed: ${err.message}`)
+				}
+				// Auto-detection: non-fatal, fall back to configured credentials
+				log.warn(`OIDC exchange failed: ${err.message}`)
+				log.warn("Falling back to stored credentials...")
+			}
+		}
+
 		// 9. Verify authentication and owner permissions
 		spinner.start()
 		spinner.text = "Verifying authentication..."
@@ -695,6 +786,9 @@ export async function publish(options = {}) {
 
 		process.exit(1)
 	} finally {
+		// Clear OIDC transient token so it doesn't leak into subsequent operations
+		clearTransientToken()
+
 		// Cleanup tarball (even on error)
 		if (tarballPath && fs.existsSync(tarballPath)) {
 			try {

package/lib/commands/skills.js

@@ -161,6 +161,15 @@ function parseSkill(rawContent, filePath) {
 		}
 	}
 
+	// Optional version field (package version when skill was authored)
+	const version = frontmatter.version
+	if (version && typeof version !== "string") {
+		return {
+			skill: null,
+			error: `${filePath}: "version" field must be a string`,
+		}
+	}
+
 	const content = markdownBody.trim()
 
 	return {
@@ -168,6 +177,7 @@ function parseSkill(rawContent, filePath) {
 			name: frontmatter.name,
 			description: frontmatter.description,
 			globs: globs && globs.length > 0 ? globs : null,
+			version: version || null,
 			content,
 			rawContent,
 			sizeBytes,

package/lib/config.js

@@ -37,12 +37,39 @@ const config = new Conf({
 // Token Management (Secure Storage)
 // ============================================================================
 
+/**
+ * Transient token — set for the duration of an OIDC-authenticated publish.
+ * Takes priority over all other token sources so the short-lived OIDC token
+ * is used without writing to keychain or mutating process.env.
+ * @type {string | null}
+ */
+let _transientToken = null
+
+/**
+ * Set a transient token that overrides all other token sources.
+ * Used by OIDC token exchange to inject a short-lived publish token.
+ * @param {string} token
+ */
+export function setTransientToken(token) {
+	_transientToken = token
+}
+
+/**
+ * Clear the transient token after use.
+ */
+export function clearTransientToken() {
+	_transientToken = null
+}
+
 /**
  * Get the stored auth token from secure storage.
- * Priority: LPM_TOKEN env var > secure storage > legacy storage
+ * Priority: transient (OIDC) > LPM_TOKEN env var > secure storage > legacy storage
  * @returns {Promise<string | null>}
  */
 export async function getToken() {
+	// OIDC-exchanged short-lived token takes highest priority
+	if (_transientToken) return _transientToken
+
 	// Check environment variable first (useful for CI/CD and testing)
 	const envToken = process.env.LPM_TOKEN
 	if (envToken) return envToken

package/lib/oidc.js

@@ -0,0 +1,138 @@
+/**
+ * OIDC (OpenID Connect) token exchange for secret-free publishing.
+ *
+ * When running in GitHub Actions with `id-token: write` permission,
+ * this module requests an OIDC JWT from GitHub and exchanges it for
+ * a short-lived LPM publish token — no LPM_TOKEN secret required.
+ *
+ * The package must have a matching trusted publisher configured in
+ * the LPM dashboard (Workflow tab) before this will succeed.
+ *
+ * @module cli/lib/oidc
+ */
+
+import { getRegistryUrl } from "./config.js"
+
+/**
+ * Detect whether we are running in GitHub Actions with OIDC available.
+ * Both env vars must be set for token request to work.
+ *
+ * @returns {boolean}
+ */
+export function isGitHubActionsWithOidc() {
+	return !!(
+		process.env.ACTIONS_ID_TOKEN_REQUEST_URL &&
+		process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN
+	)
+}
+
+/**
+ * Detect whether we are running in GitLab CI with an OIDC token injected.
+ * GitLab injects the JWT directly as an env var via id_tokens — no HTTP fetch needed.
+ *
+ * @returns {boolean}
+ */
+export function isGitLabCiWithOidc() {
+	return !!(
+		process.env.GITLAB_CI === "true" && process.env.LPM_GITLAB_OIDC_TOKEN
+	)
+}
+
+/**
+ * Exchange a GitHub Actions OIDC JWT for a short-lived LPM publish token.
+ *
+ * Steps:
+ * 1. Request an OIDC JWT from GitHub (audience: https://lpm.dev)
+ * 2. POST the JWT to the LPM OIDC token exchange endpoint
+ * 3. Return the resulting `lpm_xxx` token (valid for 15 minutes)
+ *
+ * @param {string} packageName - Full package name, e.g. "@lpm.dev/owner.pkg-name"
+ * @returns {Promise<string>} Short-lived LPM publish token
+ * @throws {Error} If GitHub OIDC request fails or LPM exchange is rejected
+ */
+export async function exchangeOidcToken(packageName) {
+	// 1. Request OIDC JWT from GitHub Actions
+	// The audience must match EXPECTED_AUDIENCE in lib/registry/oidc.js on the server
+	const githubTokenUrl = `${process.env.ACTIONS_ID_TOKEN_REQUEST_URL}&audience=https://lpm.dev`
+
+	const githubRes = await fetch(githubTokenUrl, {
+		headers: {
+			Authorization: `bearer ${process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN}`,
+		},
+	})
+
+	if (!githubRes.ok) {
+		const body = await githubRes.text().catch(() => "")
+		throw new Error(
+			`GitHub OIDC token request failed (${githubRes.status})${body ? `: ${body}` : ""}`,
+		)
+	}
+
+	const { value: oidcJwt } = await githubRes.json()
+	if (!oidcJwt) {
+		throw new Error("GitHub OIDC response did not contain a token value")
+	}
+
+	// 2. Exchange the OIDC JWT for a short-lived LPM publish token
+	const registryUrl = getRegistryUrl()
+	const exchangeRes = await fetch(`${registryUrl}/api/registry/-/token/oidc`, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({ token: oidcJwt, package: packageName }),
+	})
+
+	if (!exchangeRes.ok) {
+		const body = await exchangeRes.text().catch(() => "")
+		throw new Error(
+			`OIDC token exchange failed (${exchangeRes.status})${body ? `: ${body}` : ""}`,
+		)
+	}
+
+	const { token } = await exchangeRes.json()
+	if (!token) {
+		throw new Error("OIDC exchange response did not contain a token")
+	}
+
+	return token
+}
+
+/**
+ * Exchange a GitLab CI OIDC JWT for a short-lived LPM publish token.
+ *
+ * GitLab injects the JWT directly into LPM_GITLAB_OIDC_TOKEN via id_tokens — no
+ * intermediate HTTP fetch is needed (unlike GitHub Actions).
+ *
+ * @param {string} packageName - Full package name, e.g. "@lpm.dev/owner.pkg-name"
+ * @returns {Promise<string>} Short-lived LPM publish token
+ * @throws {Error} If the OIDC token is missing or the LPM exchange is rejected
+ */
+export async function exchangeGitLabOidcToken(packageName) {
+	const oidcJwt = process.env.LPM_GITLAB_OIDC_TOKEN
+	if (!oidcJwt) {
+		throw new Error(
+			"LPM_GITLAB_OIDC_TOKEN is not set. " +
+				"Add id_tokens: LPM_GITLAB_OIDC_TOKEN: { aud: https://lpm.dev } to your .gitlab-ci.yml",
+		)
+	}
+
+	const registryUrl = getRegistryUrl()
+	const exchangeRes = await fetch(`${registryUrl}/api/registry/-/token/oidc`, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({ token: oidcJwt, package: packageName }),
+	})
+
+	if (!exchangeRes.ok) {
+		const body = await exchangeRes.text().catch(() => "")
+		throw new Error(
+			`OIDC token exchange failed (${exchangeRes.status})${body ? `: ${body}` : ""}`,
+		)
+	}
+
+	const { token } = await exchangeRes.json()
+	if (!token) {
+		throw new Error("OIDC exchange response did not contain a token")
+	}
+
+	return token
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@lpm-registry/cli",
-	"version": "0.2.0",
+	"version": "0.2.1",
 	"description": "CLI for Licensed Package Manager",
 	"author": "LPM <hello@lpm.dev> (https://lpm.dev)",
 	"repository": {