opkg 0.6.1 → 0.7.0

package/dist/utils/package-local-files.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"package-local-files.js","sourceRoot":"","sources":["../../src/utils/package-local-files.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,2BAA2B,EAAE,MAAM,mBAAmB,CAAC;AAEhE,MAAM,CAAC,KAAK,UAAU,6BAA6B,CAAC,UAAkB;IACpE,OAAO,MAAM,2BAA2B,CAAC,UAAU,CAAC,CAAC;AACvD,CAAC"}

package/dist/utils/path-matching.js

@@ -1,74 +0,0 @@
-import { normalize } from 'path';
-/**
- * Cross-platform path matching utilities
- * Provides consistent path matching logic across different filesystem types
- */
-/**
- * Determine if we're on a case-insensitive filesystem (primarily Windows)
- */
-export function isCaseInsensitiveFilesystem() {
-    return process.platform === 'win32';
-}
-/**
- * Normalize a path for cross-platform comparison
- * Ensures consistent forward slashes and optional case-insensitive comparison
- */
-export function normalizePathForComparison(path, caseInsensitive = isCaseInsensitiveFilesystem()) {
-    const normalized = normalize(path).replace(/\\/g, '/'); // Ensure forward slashes for consistent processing
-    return caseInsensitive ? normalized.toLowerCase() : normalized;
-}
-/**
- * Match a path against platform directory patterns and extract relative path
- * Handles both absolute and relative path patterns across different filesystem types
- */
-export function matchPlatformPattern(inputPath, platformDir, caseInsensitive = isCaseInsensitiveFilesystem()) {
-    // Normalize paths for comparison
-    const normalizedInputPath = normalizePathForComparison(inputPath, caseInsensitive);
-    const normalizedPlatformDir = caseInsensitive ? platformDir.toLowerCase() : platformDir;
-    const comparePath = normalizedInputPath;
-    // Check for platform directory patterns
-    const absPlatformPattern = `/${normalizedPlatformDir}/`;
-    const relPlatformPattern = `${normalizedPlatformDir}/`;
-    let platformIndex = comparePath.indexOf(absPlatformPattern);
-    let isAbsPattern = true;
-    if (platformIndex === -1) {
-        platformIndex = comparePath.indexOf(relPlatformPattern);
-        isAbsPattern = false;
-    }
-    if (platformIndex !== -1) {
-        // Extract the relative path after the platform directory
-        const patternLength = isAbsPattern ? absPlatformPattern.length - 1 : relPlatformPattern.length - 1;
-        let relativePath = normalizedInputPath.substring(platformIndex + patternLength);
-        // Remove leading separator if present
-        if (relativePath.startsWith('/') || relativePath.startsWith('\\')) {
-            relativePath = relativePath.substring(1);
-        }
-        return { relativePath, isAbsoluteMatch: isAbsPattern };
-    }
-    // Check for exact platform directory matches
-    const exactAbsMatch = `/${normalizedPlatformDir}`;
-    const exactRelMatch = normalizedPlatformDir;
-    const exactMatches = [
-        comparePath === exactAbsMatch,
-        comparePath === exactRelMatch,
-        comparePath.endsWith(absPlatformPattern.slice(0, -1)), // ends with /platformDir
-        comparePath.endsWith(relPlatformPattern.slice(0, -1)) // ends with platformDir
-    ];
-    if (exactMatches.some(match => match)) {
-        return { relativePath: '', isAbsoluteMatch: comparePath.startsWith('/') };
-    }
-    return null;
-}
-/**
- * Check if a path exactly matches a platform directory (for root directory detection)
- */
-export function isExactPlatformMatch(inputPath, platformDir, caseInsensitive = isCaseInsensitiveFilesystem()) {
-    const comparePath = normalizePathForComparison(inputPath, caseInsensitive);
-    const normalizedPlatformDir = caseInsensitive ? platformDir.toLowerCase() : platformDir;
-    const exactAbsMatch = `/${normalizedPlatformDir}`;
-    const exactRelMatch = normalizedPlatformDir;
-    return comparePath === exactAbsMatch ||
-        comparePath === exactRelMatch ||
-        comparePath.endsWith(`/${normalizedPlatformDir}`);
-}
-//# sourceMappingURL=path-matching.js.map

package/dist/utils/path-matching.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"path-matching.js","sourceRoot":"","sources":["../../src/utils/path-matching.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AAEjC;;;GAGG;AAEH;;GAEG;AACH,MAAM,UAAU,2BAA2B;IACzC,OAAO,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC;AACtC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,0BAA0B,CAAC,IAAY,EAAE,kBAA2B,2BAA2B,EAAE;IAC/G,MAAM,UAAU,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,mDAAmD;IAC3G,OAAO,eAAe,CAAC,CAAC,CAAC,UAAU,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC;AACjE,CAAC;AAUD;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAClC,SAAiB,EACjB,WAAmB,EACnB,kBAA2B,2BAA2B,EAAE;IAExD,iCAAiC;IACjC,MAAM,mBAAmB,GAAG,0BAA0B,CAAC,SAAS,EAAE,eAAe,CAAC,CAAC;IACnF,MAAM,qBAAqB,GAAG,eAAe,CAAC,CAAC,CAAC,WAAW,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC;IACxF,MAAM,WAAW,GAAG,mBAAmB,CAAC;IAExC,wCAAwC;IACxC,MAAM,kBAAkB,GAAG,IAAI,qBAAqB,GAAG,CAAC;IACxD,MAAM,kBAAkB,GAAG,GAAG,qBAAqB,GAAG,CAAC;IAEvD,IAAI,aAAa,GAAG,WAAW,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAC5D,IAAI,YAAY,GAAG,IAAI,CAAC;IAExB,IAAI,aAAa,KAAK,CAAC,CAAC,EAAE,CAAC;QACzB,aAAa,GAAG,WAAW,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC;QACxD,YAAY,GAAG,KAAK,CAAC;IACvB,CAAC;IAED,IAAI,aAAa,KAAK,CAAC,CAAC,EAAE,CAAC;QACzB,yDAAyD;QACzD,MAAM,aAAa,GAAG,YAAY,CAAC,CAAC,CAAC,kBAAkB,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,kBAAkB,CAAC,MAAM,GAAG,CAAC,CAAC;QACnG,IAAI,YAAY,GAAG,mBAAmB,CAAC,SAAS,CAAC,aAAa,GAAG,aAAa,CAAC,CAAC;QAEhF,sCAAsC;QACtC,IAAI,YAAY,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,YAAY,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YAClE,YAAY,GAAG,YAAY,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;QAC3C,CAAC;QAED,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,YAAY,EAAE,CAAC;IACzD,CAAC;IAED,6CAA6C;IAC7C,MAAM,aAAa,GAAG,IAAI,qBAAqB,EAAE,CAAC;IAClD,MAAM,aAAa,GAAG,qBAAqB,CAAC;IAE5C,MAAM,YAAY,GAAG;QACnB,WAAW,KAAK,aAAa;QAC7B,WAAW,KAAK,aAAa;QAC7B,WAAW,CAAC,QAAQ,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,yBAAyB;QAChF,WAAW,CAAC,QAAQ,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAG,wBAAwB;KACjF,CAAC;IAEF,IAAI,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC;QACtC,OAAO,EAAE,YAAY,EAAE,EAAE,EAAE,eAAe,EAAE,WAAW,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;IAC5E,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAClC,SAAiB,EACjB,WAAmB,EACnB,kBAA2B,2BAA2B,EAAE;IAExD,MAAM,WAAW,GAAG,0BAA0B,CAAC,SAAS,EAAE,eAAe,CAAC,CAAC;IAC3E,MAAM,qBAAqB,GAAG,eAAe,CAAC,CAAC,CAAC,WAAW,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC;IAExF,MAAM,aAAa,GAAG,IAAI,qBAAqB,EAAE,CAAC;IAClD,MAAM,aAAa,GAAG,qBAAqB,CAAC;IAE5C,OAAO,WAAW,KAAK,aAAa;QAC7B,WAAW,KAAK,aAAa;QAC7B,WAAW,CAAC,QAAQ,CAAC,IAAI,qBAAqB,EAAE,CAAC,CAAC;AAC3D,CAAC"}

package/dist/utils/root-file-operations.js

@@ -1,39 +0,0 @@
-/**
- * Root File Operations Utility
- * Utility functions for operating on root files (AGENTS.md, CLAUDE.md, etc.)
- */
-import { extractPackageContentFromRootFile } from './root-file-extractor.js';
-import { mergePackageContentIntoRootFile } from './root-file-merger.js';
-import { readTextFile, writeTextFile } from './fs.js';
-import { logger } from './logger.js';
-import { getPathLeaf } from './path-normalization.js';
-/**
- * Add a package marker to a root file if not already present
- *
- * @param filePath - Path to the root file
- * @param packageName - Name of the package to add
- * @returns Result indicating if the file was processed and why
- */
-export async function addPackageToRootFile(filePath, packageName) {
-    logger.debug(`Processing root file: ${filePath}`);
-    try {
-        const content = await readTextFile(filePath);
-        // Check if package marker already exists
-        const existingContent = extractPackageContentFromRootFile(content, packageName);
-        if (existingContent !== null) {
-            console.log(`✓ Package '${packageName}' is already added to ${getPathLeaf(filePath)}`);
-            return { processed: false, reason: 'already_exists' };
-        }
-        // Add empty marker section at the end
-        const updatedContent = mergePackageContentIntoRootFile(content, packageName, '');
-        await writeTextFile(filePath, updatedContent);
-        console.log(`✓ Added package marker for '${packageName}' to ${getPathLeaf(filePath)}`);
-        return { processed: true };
-    }
-    catch (error) {
-        logger.error(`Failed to process root file: ${filePath}`, { error });
-        console.log(`✗ Failed to process ${getPathLeaf(filePath)}: ${error}`);
-        return { processed: false, reason: 'error' };
-    }
-}
-//# sourceMappingURL=root-file-operations.js.map

package/dist/utils/root-file-operations.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"root-file-operations.js","sourceRoot":"","sources":["../../src/utils/root-file-operations.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,iCAAiC,EAAE,MAAM,0BAA0B,CAAC;AAC7E,OAAO,EAAE,+BAA+B,EAAE,MAAM,uBAAuB,CAAC;AACxE,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACtD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAUtD;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,QAAgB,EAChB,WAAmB;IAEnB,MAAM,CAAC,KAAK,CAAC,yBAAyB,QAAQ,EAAE,CAAC,CAAC;IAElD,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,YAAY,CAAC,QAAQ,CAAC,CAAC;QAE7C,yCAAyC;QACzC,MAAM,eAAe,GAAG,iCAAiC,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;QAChF,IAAI,eAAe,KAAK,IAAI,EAAE,CAAC;YAC7B,OAAO,CAAC,GAAG,CAAC,cAAc,WAAW,yBAAyB,WAAW,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;YACvF,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC;QACxD,CAAC;QAED,sCAAsC;QACtC,MAAM,cAAc,GAAG,+BAA+B,CAAC,OAAO,EAAE,WAAW,EAAE,EAAE,CAAC,CAAC;QACjF,MAAM,aAAa,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC;QAE9C,OAAO,CAAC,GAAG,CAAC,+BAA+B,WAAW,QAAQ,WAAW,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;QACvF,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IAE7B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,KAAK,CAAC,gCAAgC,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QACpE,OAAO,CAAC,GAAG,CAAC,uBAAuB,WAAW,CAAC,QAAQ,CAAC,KAAK,KAAK,EAAE,CAAC,CAAC;QACtE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;IAC/C,CAAC;AACH,CAAC"}

package/dist/utils/root-file-transformer.js

@@ -1,27 +0,0 @@
-/**
- * Root File Transformer Utility
- * Handles transformation of root file content for package operations
- */
-import { extractPackageSection, buildOpenMarker, CLOSE_MARKER } from './root-file-extractor.js';
-/**
- * Transform root file content for package renaming
- * Updates package name in markers
- *
- * @param content - The root file content
- * @param oldPackageName - The original package name in the marker
- * @param newPackageName - The new package name to use in the marker
- * @returns Updated content with new package name
- */
-export function transformRootFileContent(content, oldPackageName, newPackageName) {
-    // Extract the current package section
-    const extracted = extractPackageSection(content, oldPackageName);
-    if (!extracted) {
-        // No valid marker found for the old package name, return unchanged
-        return content;
-    }
-    // Build new marker with updated name
-    const newMarker = buildOpenMarker(newPackageName);
-    // Reconstruct the content with updated marker
-    return newMarker + '\n' + extracted.sectionBody + '\n' + CLOSE_MARKER;
-}
-//# sourceMappingURL=root-file-transformer.js.map

package/dist/utils/root-file-transformer.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"root-file-transformer.js","sourceRoot":"","sources":["../../src/utils/root-file-transformer.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAEhG;;;;;;;;GAQG;AACH,MAAM,UAAU,wBAAwB,CACtC,OAAe,EACf,cAAsB,EACtB,cAAsB;IAEtB,sCAAsC;IACtC,MAAM,SAAS,GAAG,qBAAqB,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;IACjE,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,mEAAmE;QACnE,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,qCAAqC;IACrC,MAAM,SAAS,GAAG,eAAe,CAAC,cAAc,CAAC,CAAC;IAElD,8CAA8C;IAC9C,OAAO,SAAS,GAAG,IAAI,GAAG,SAAS,CAAC,WAAW,GAAG,IAAI,GAAG,YAAY,CAAC;AACxE,CAAC"}

package/dist/utils/yaml-frontmatter.js

@@ -1,25 +0,0 @@
-import * as yaml from 'js-yaml';
-import { isScopedName } from '../core/scoping/package-scoping';
-/**
- * Generate a properly quoted YAML key-value pair
- */
-export function generateYamlKeyValue(key, value, indent = '') {
-    // For boolean values, just output as-is
-    if (typeof value === 'boolean') {
-        return `${indent}${key}: ${value}`;
-    }
-    // For strings, use js-yaml to ensure proper quoting
-    if (typeof value === 'string') {
-        // Check if this is a scoped name (starts with @) - these need explicit quoting
-        const isScoped = isScopedName(value);
-        const quotedValue = yaml.dump(value, {
-            flowLevel: 0,
-            quotingType: '"', // Prefer double quotes for consistency
-            forceQuotes: isScoped // Force quotes for scoped names
-        }).trim();
-        return `${indent}${key}: ${quotedValue}`;
-    }
-    // For other types, fallback to string conversion
-    return `${indent}${key}: ${String(value)}`;
-}
-//# sourceMappingURL=yaml-frontmatter.js.map

package/dist/utils/yaml-frontmatter.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"yaml-frontmatter.js","sourceRoot":"","sources":["../../src/utils/yaml-frontmatter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAE/D;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAW,EAAE,KAAU,EAAE,SAAiB,EAAE;IAC/E,wCAAwC;IACxC,IAAI,OAAO,KAAK,KAAK,SAAS,EAAE,CAAC;QAC/B,OAAO,GAAG,MAAM,GAAG,GAAG,KAAK,KAAK,EAAE,CAAC;IACrC,CAAC;IAED,oDAAoD;IACpD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,+EAA+E;QAC/E,MAAM,QAAQ,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;QAErC,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE;YACnC,SAAS,EAAE,CAAC;YACZ,WAAW,EAAE,GAAG,EAAG,uCAAuC;YAC1D,WAAW,EAAE,QAAQ,CAAE,gCAAgC;SACxD,CAAC,CAAC,IAAI,EAAE,CAAC;QAEV,OAAO,GAAG,MAAM,GAAG,GAAG,KAAK,WAAW,EAAE,CAAC;IAC3C,CAAC;IAED,iDAAiD;IACjD,OAAO,GAAG,MAAM,GAAG,GAAG,KAAK,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;AAC7C,CAAC"}

package/specs/auth/auth-device-flow.md

@@ -1,70 +0,0 @@
-# opkg login – Device Authorization Flow (RFC 8628)
-
-## Goals
-- Add `opkg login [--profile <name>]` using OAuth 2.0 Device Authorization Grant.
-- Store bearer tokens per profile; keep API-key auth backward compatible.
-
-## Command behavior
-- Syntax: `opkg login [--profile <name>]`
-- Profile: optional; defaults to `default`.
-- Flow:
-  1) Start device authorization → get `device_code`, `user_code`, `verification_uri`, `verification_uri_complete`, `expires_in`, `interval`.
-  2) Print code/URL; attempt to open browser to `verification_uri_complete`.
-  3) Poll token endpoint until success/denied/expired/timeout.
-  4) On success, persist access/refresh tokens to the selected profile.
-  5) On failure, show actionable error and exit non-zero.
-
-## HTTP interactions (backend contract)
-- POST `/auth/device/authorize` (no auth):
-  - Body: `{ clientId: 'opkg-cli', scope?: 'openid', deviceName?: 'opkg-cli' }`
-  - Response: `{ device_code, user_code, verification_uri, verification_uri_complete, expires_in, interval }`
-- POST `/auth/device/token` (no auth):
-  - Body: `{ deviceCode }`
-  - Success: `{ access_token, refresh_token, token_type: 'bearer', expires_in }`
-  - Error codes (HTTP 400): `authorization_pending`, `slow_down`, `expired_token`, `access_denied`
-- POST `/auth/refresh` (no auth) for refresh flow:
-  - Body: `{ refreshToken }`
-  - Success: `{ accessToken, refreshToken }`
-
-## CLI storage & auth selection
-- Extend `ProfileCredentials` to include `access_token`, `refresh_token`, `expires_at`, `token_type`.
-- Credentials persisted in the existing profile credentials INI; preserve existing `api_key`.
-- Header selection:
-  - Prefer non-expired access token → `Authorization: Bearer <token>`.
-  - If expired and refresh token present → call `/auth/refresh`, persist new pair.
-  - Fallback: `X-API-Key` if present.
-  - If none: instruct user to run `opkg login` or configure API key.
-
-## UX requirements
-- Print user code and verification URL.
-- Open browser best-effort; if it fails, user can manually visit the URL.
-- Poll respecting `interval`; on `slow_down` add +5s each time.
-- Time out when `expires_in` elapses; show “code expired, rerun opkg login.”
-- Errors:
-  - `access_denied`: “Access denied. Please restart opkg login.”
-  - `expired_token`: “Code expired. Please rerun opkg login.”
-
-## Persistence details
-- `expires_at` derived from `Date.now() + expires_in*1000` or JWT `exp`.
-- When refreshing, keep existing `api_key` intact in the profile record.
-
-## Edge cases & fallbacks
-- If profile missing: create credentials entry when saving tokens.
-- If refresh fails: drop to API key if present; otherwise require login.
-- Platform-specific browser open: `open` (mac), `start` (win), `xdg-open` (linux); ignore failures.
-
-## Logout command
-- Syntax: `opkg logout [--profile <name>]`
-- Requires stored OAuth tokens for the profile; no-op if none.
-- Sends `POST /auth/logout` with bearer auth and `{ refreshToken }` body.
-- On success or failure, clears local token store entry; keeps any configured API key.
-- If profile resolved as direct API key usage, exit with “no OAuth session.”
-
-## Telemetry/logging (minimal)
-- Debug log start/stop of poll, slow_down adjustments, refresh attempts.
-- Do not log tokens.
-
-## Non-goals (future)
-- Device-name flag, headless/no-browser flag.
-- Multi-factor UX in CLI.
-

package/specs/login/login-device-flow.md

@@ -1,70 +0,0 @@
-# opkg login – Device Authorization Flow (RFC 8628)
-
-## Goals
-- Add `opkg login [--profile <name>]` using OAuth 2.0 Device Authorization Grant.
-- Store bearer tokens per profile; keep API-key auth backward compatible.
-
-## Command behavior
-- Syntax: `opkg login [--profile <name>]`
-- Profile: optional; defaults to `default`.
-- Flow:
-  1) Start device authorization → get `device_code`, `user_code`, `verification_uri`, `verification_uri_complete`, `expires_in`, `interval`.
-  2) Print code/URL; attempt to open browser to `verification_uri_complete`.
-  3) Poll token endpoint until success/denied/expired/timeout.
-  4) On success, persist access/refresh tokens to the selected profile.
-  5) On failure, show actionable error and exit non-zero.
-
-## HTTP interactions (backend contract)
-- POST `/auth/device/authorize` (no auth):
-  - Body: `{ clientId: 'opkg-cli', scope?: 'openid', deviceName?: 'opkg-cli' }`
-  - Response: `{ device_code, user_code, verification_uri, verification_uri_complete, expires_in, interval }`
-- POST `/auth/device/token` (no auth):
-  - Body: `{ deviceCode }`
-  - Success: `{ access_token, refresh_token, token_type: 'bearer', expires_in }`
-  - Error codes (HTTP 400): `authorization_pending`, `slow_down`, `expired_token`, `access_denied`
-- POST `/auth/refresh` (no auth) for refresh flow:
-  - Body: `{ refreshToken }`
-  - Success: `{ accessToken, refreshToken }`
-
-## CLI storage & auth selection
-- Extend `ProfileCredentials` to include `access_token`, `refresh_token`, `expires_at`, `token_type`.
-- Credentials persisted in the existing profile credentials INI; preserve existing `api_key`.
-- Header selection:
-  - Prefer non-expired access token → `Authorization: Bearer <token>`.
-  - If expired and refresh token present → call `/auth/refresh`, persist new pair.
-  - Fallback: `X-API-Key` if present.
-  - If none: instruct user to run `opkg login` or configure API key.
-
-## UX requirements
-- Print user code and verification URL.
-- Open browser best-effort; if it fails, user can manually visit the URL.
-- Poll respecting `interval`; on `slow_down` add +5s each time.
-- Time out when `expires_in` elapses; show “code expired, rerun opkg login.”
-- Errors:
-  - `access_denied`: “Access denied. Please restart opkg login.”
-  - `expired_token`: “Code expired. Please rerun opkg login.”
-
-## Persistence details
-- `expires_at` derived from `Date.now() + expires_in*1000` or JWT `exp`.
-- When refreshing, keep existing `api_key` intact in the profile record.
-
-## Edge cases & fallbacks
-- If profile missing: create credentials entry when saving tokens.
-- If refresh fails: drop to API key if present; otherwise require login.
-- Platform-specific browser open: `open` (mac), `start` (win), `xdg-open` (linux); ignore failures.
-
-## Logout command
-- Syntax: `opkg logout [--profile <name>]`
-- Requires stored OAuth tokens for the profile; no-op if none.
-- Sends `POST /auth/logout` with bearer auth and `{ refreshToken }` body.
-- On success or failure, clears local token store entry; keeps any configured API key.
-- If profile resolved as direct API key usage, exit with “no OAuth session.”
-
-## Telemetry/logging (minimal)
-- Debug log start/stop of poll, slow_down adjustments, refresh attempts.
-- Do not log tokens.
-
-## Non-goals (future)
-- Device-name flag, headless/no-browser flag.
-- Multi-factor UX in CLI.
-

package/specs/platforms.md

@@ -1,193 +0,0 @@
-## Platforms system behavior
-
-### Overview
-
-The platforms system provides a unified way to describe and work with different AI coding platforms (e.g. Cursor, Claude, Gemini) so that OpenPackage can manage platform‑specific rules, commands, agents, and skills consistently.
-
-From a user’s perspective, the platform layer answers:
-- **Which platforms are supported in this workspace?**
-- **Where do their files live on disk?**
-- **Which files belong to which platform (or to the generic `ai` space)?**
-- **Which root files (e.g. `CLAUDE.md`) are active, and how are they used?**
-
-All platform definitions (names, directories, root files, and subdirectories) are centralized in `platforms.jsonc`.
-
-Each platform entry in `platforms.jsonc` has the shape:
-
-- `name` (string): Human‑readable display name.
-- `rootDir` (string): Platform root directory (e.g. `.cursor`, `.claude`).
-- `rootFile?` (string): Optional root file at the project root (e.g. `CLAUDE.md`, `QWEN.md`).
-- `subdirs` (object): Map from universal subdir keys (`rules`, `commands`, `agents`, `skills`) to:
-  - `path` (string): Directory path under `rootDir`.
-  - `exts?` (string[]): Allowed workspace file extensions. When omitted, all extensions are allowed; when an empty array, no extensions are allowed.
-  - `transformations?` (array): Optional extension conversion rules with `{ packageExt, workspaceExt }` entries that describe how files convert between registry and workspace formats.
-- `aliases?` (string[]): Optional CLI aliases that resolve to this platform.
-- `enabled?` (boolean): When `false`, the platform exists in config but is treated as disabled.
-
----
-
-### Platform identities and aliases
-
-- **Platform id**: each platform has a lowercase id (e.g. `cursor`, `claude`, `gemini`) used throughout the CLI. These ids are the top‑level keys in `platforms.jsonc`.
-- **Enabled flag**:
-  - Platforms are considered **enabled by default**.
-  - A platform can be explicitly disabled in `platforms.jsonc` via `enabled: false` (e.g. for experimental or unsupported platforms).
-  - Functions that list or iterate platforms only include **enabled** platforms by default, with optional flags to include disabled ones when needed.
-- **Aliases**:
-  - Each platform can declare **human‑friendly aliases** in its `aliases` array (e.g. `claudecode`, `codexcli`, `geminicli`, `kilocode`, `qwencode`).
-  - Aliases are resolved case‑insensitively to a canonical platform id.
-  - User‑facing prompts or configs can accept either the platform id or any of its aliases.
-
-**Resolution behavior**
-
-- Given a string input (e.g. from CLI flags, prompts, or config), the system:
-  - First treats it as a platform id (after lowercasing).
-  - If there is no direct match, it looks it up in the alias map.
-  - If neither match, the platform is treated as **unknown**.
-
----
-
-### Directory layout and universal subdirs
-
-Each platform defines:
-- A **root directory** (e.g. `.cursor`, `.claude`, `.gemini`).
-- Optional **root file** at the project root (e.g. `CLAUDE.md`, `GEMINI.md`, `QWEN.md`, `WARP.md`, or the shared `AGENTS.md`).
-- A set of **universal subdirectories**, which describe where different kinds of content live:
-  - `rules` – steering/rules files for a platform.
-  - `commands` – command/workflow prompt files.
-  - `agents` – agent definitions.
-  - `skills` – skill or tool definitions.
-
-For each subdirectory, the platform definition specifies:
-- **Path** under the platform root (e.g. `.cursor/rules`, `.factory/droids`, `.kilo/workflows`).
-- **Allowed extensions**: which workspace file extensions are considered part of that subdir (e.g. `.md`, `.mdc`, `.toml`). Omit to allow any extension or set an empty list to disallow all files.
-- **Extension transformations**: optional `{ packageExt, workspaceExt }` pairs that describe how files convert between registry/universal formats and platform-specific workspace formats (e.g. Cursor rules convert `.md` registry files to `.mdc` in the workspace).
-
-**Examples**
-
-- Cursor:
-  - Root dir: `.cursor`
-  - Subdirs:
-    - `rules` → `.cursor/rules` (reads `.mdc` + `.md`, writes `.mdc`)
-    - `commands` → `.cursor/commands` (reads/writes `.md`)
-- Claude:
-  - Root dir: `.claude`
-  - Root file: `CLAUDE.md`
-  - Subdirs:
-    - `commands` → `.claude/commands`
-    - `agents` → `.claude/agents`
-    - `skills` → `.claude/skills`
-
-The system exposes a **platform directory map** that, given a working directory, tells callers where each platform’s `rules`, `commands`, `agents`, and `skills` live on disk.
-
----
-
-### Platform detection
-
-The platforms system can **detect which platforms are present** in a workspace using two signals:
-
-1. **Platform directories**:
-   - For each enabled platform, the system checks whether its root directory exists in the current working directory.
-   - If the root directory exists, the platform is marked as **present**.
-
-2. **Root files**:
-   - For platforms that define a root file (e.g. `CLAUDE.md`, `GEMINI.md`, `QWEN.md`, `WARP.md`), the system checks whether those files exist at the project root.
-   - If a root file exists, the corresponding platform is also marked as **present**, even if its standard directory structure is missing.
-   - The shared `AGENTS.md` file is treated as **universal** and not attributed to a single platform.
-
-The result is:
-- A list of **detection results** (for each platform: `{ name, detected }`).
-- A convenience list of **detected platforms only** (used by higher‑level features like setup flows).
-
----
-
-### Platform‑specific directories and creation
-
-The platforms system provides helpers for:
-
-- **Getting directory paths** for each platform:
-  - For each enabled platform, callers can retrieve:
-    - The `rules` directory path.
-    - Optional `commands`, `agents`, and `skills` directory paths.
-    - Optional `rootFile` path, if the platform defines one.
-- **Creating missing platform directories**:
-  - Given a list of platform ids and a working directory:
-    - Ensures the `rules` directory exists for each platform.
-    - Creates directories as needed and returns a list of newly created paths.
-
-These helpers allow commands like `opkg init` or platform setup flows to create the necessary folder structure for one or more platforms.
-
----
-
-### Validating platform structure
-
-For a given platform and working directory, the system can validate:
-- That the `rules` directory exists.
-- That the configured root file (if any) exists.
-
-It returns:
-- A simple `{ valid: boolean, issues: string[] }` result:
-  - `valid = true` when the platform’s required directories/files are present.
-  - `issues` describing any missing or inconsistent paths.
-
-This is used by higher‑level commands to surface actionable warnings when a platform’s layout is incomplete.
-
----
-
-### File extension behavior
-
-For each platform’s `rules` subdir, the system exposes:
-- The **set of file extensions** that are considered valid rules files for that platform.
-  - Example: Cursor rules accept `.mdc` and `.md`, Gemini commands accept `.toml`, etc.
-- Higher‑level discovery utilities rely on this to:
-  - Filter files by extension when searching for platform content.
-  - Decide which files are safe to manage or delete during uninstall/cleanup operations.
-
----
-
-### Universal subdirectory listing
-
-For any detected platform, the platforms system can return a **normalized list of its subdirectories**:
-- Each entry includes:
-  - The full directory path.
-  - The universal label (`rules`, `commands`, `agents`, `skills`).
-  - A short leaf name (last path component) for display.
-
-This list is consumed by:
-- Discovery utilities that search for platform‑specific files.
-- Uninstall/cleanup flows that remove platform files for a given package.
-
----
-
-### Platform inference from file paths
-
-The platforms system helps determine which platform a given file belongs to by:
-
-1. **Using path‑to‑platform mappings**:
-   - A dedicated mapper converts full workspace paths into a *universal* representation that includes the platform id where possible (e.g. `.cursor/rules/foo.mdc` → platform `cursor` + `rules/foo.mdc`).
-
-2. **Checking for generic workspace directories**:
-   - Files that do not live under a known platform root (for example, a conventional `ai/` folder) are treated as workspace-level content rather than being assigned to a specific platform.
-
-3. **Looking at source directory names**:
-   - If a file lives under a known platform root directory (e.g. `.cursor`, `.claude`), the system infers that platform from the directory.
-
-4. **Parsing registry paths with platform suffixes**:
-   - As a final fallback, the system inspects registry paths for explicit platform suffixes (e.g. `rules/file.cursor.md`) and maps them back to a platform id when possible.
-
-The result is a best‑effort platform id (or a `workspace` classification) for a given file, which other components use to route content to the right registry paths and conflict‑resolution logic.
-
----
-
-### Root file handling
-
-The platforms system exposes **all known platform root filenames**, derived from the `rootFile` fields in `platforms.jsonc` plus the universal `AGENTS.md`. These are used to:
-- Discover root files in the workspace or in the local registry.
-- Map root files back to platforms (except for universal `AGENTS.md`).
-- Coordinate how content from multiple platform‑specific root files is merged or extracted into a universal view (handled by other utilities).
-
-From a behavioral perspective:
-- Platforms that define root files can participate in root‑file‑based flows (e.g. reading/writing `CLAUDE.md`).
-- Platforms without root files rely exclusively on their directory layout (`.cursor/rules`, `.kilo/workflows`, etc.).
-
-