opkg 0.9.0 → 0.9.2

package/packages/core/dist/utils/resource-arg-parser.js

@@ -0,0 +1,231 @@
+/**
+ * Unified resource argument parsing for the install command.
+ *
+ * Parses resource specifications in priority order:
+ * 1. URL (GitHub URLs)
+ * 2. Resource Name (with or without `@` symbol)
+ * 3. Filepath (absolute or relative)
+ *
+ * Supports version specifications only at repo/package level, not on sub-paths.
+ */
+import { resolve, isAbsolute } from 'path';
+import { exists } from './fs.js';
+import { parseGitHubUrl, parseGitHubShorthand } from './git-url-detection.js';
+import { ValidationError } from './errors.js';
+import { logger } from './logger.js';
+/**
+ * Parse a resource argument string into a ResourceSpec.
+ *
+ * Resolution order:
+ * 1. GitHub URL → Extract repo + path
+ * 2. GitHub Shorthand (gh@) → Parse segments
+ * 3. Filepath → Resolve and validate
+ * 4. Registry Name → Parse name + version
+ *
+ * @param input - Raw user input
+ * @param cwd - Current working directory for resolving relative paths
+ * @returns Parsed ResourceSpec
+ */
+export async function parseResourceArg(input, cwd = process.cwd()) {
+    if (!input || typeof input !== 'string') {
+        throw new ValidationError('Resource argument cannot be empty');
+    }
+    // 1. GitHub URL
+    if (input.startsWith('https://github.com/') || input.startsWith('http://github.com/')) {
+        return parseGitHubUrlResource(input);
+    }
+    // 2. GitHub shorthand
+    if (input.startsWith('gh@')) {
+        return parseGitHubShorthandResource(input);
+    }
+    // 3. Filepath detection (before registry to avoid false positives)
+    if (looksLikePath(input)) {
+        const resolved = isAbsolute(input) ? input : resolve(cwd, input);
+        if (await exists(resolved)) {
+            const stat = await import('fs/promises').then(m => m.stat(resolved));
+            return {
+                type: 'filepath',
+                absolutePath: resolved,
+                isDirectory: stat.isDirectory()
+            };
+        }
+        // Path syntax but doesn't exist - could still be registry
+        // Only error if it's unambiguously a path
+        if (isUnambiguouslyPath(input)) {
+            throw new ValidationError(`Path not found: ${input}`);
+        }
+    }
+    // 4. Registry resource name
+    return parseRegistryResource(input);
+}
+/**
+ * Parse a GitHub URL into a ResourceSpec.
+ */
+function parseGitHubUrlResource(input) {
+    const gitSpec = parseGitHubUrl(input);
+    if (!gitSpec) {
+        throw new ValidationError(`Invalid GitHub URL: ${input}`);
+    }
+    // Extract owner/repo from the git URL
+    const match = gitSpec.url.match(/github\.com[/:]([\w-]+)\/([\w-]+)(?:\.git)?$/);
+    if (!match) {
+        throw new ValidationError(`Could not extract repository from URL: ${input}`);
+    }
+    const [, owner, repo] = match;
+    logger.debug('Parsed GitHub URL resource', {
+        input,
+        repo: `${owner}/${repo}`,
+        ref: gitSpec.ref,
+        path: gitSpec.path
+    });
+    return {
+        type: 'github-url',
+        repo: `${owner}/${repo}`,
+        gitUrl: gitSpec.url,
+        ref: gitSpec.ref,
+        path: gitSpec.path
+    };
+}
+/**
+ * Parse GitHub shorthand (gh@owner/repo[/path][@version]) into a ResourceSpec.
+ */
+function parseGitHubShorthandResource(input) {
+    // Check for version at the end first
+    let baseInput = input;
+    let version;
+    // Look for @version at the end (after repo identifier)
+    // Format: gh@owner/repo[@version][/path]
+    // We need to be careful: gh@owner/repo@v1.0/path vs gh@owner/repo/path
+    const segments = input.slice(3).split('/'); // Remove 'gh@'
+    if (segments.length >= 2) {
+        // Check if second segment has @version
+        const repoSegment = segments[1];
+        const atIndex = repoSegment.indexOf('@');
+        if (atIndex > 0) {
+            version = repoSegment.slice(atIndex + 1);
+            segments[1] = repoSegment.slice(0, atIndex);
+            baseInput = 'gh@' + segments.join('/');
+        }
+    }
+    const gitSpec = parseGitHubShorthand(baseInput);
+    if (!gitSpec) {
+        throw new ValidationError(`Invalid GitHub shorthand: ${input}`);
+    }
+    // Extract owner/repo from the git URL
+    const match = gitSpec.url.match(/github\.com[/:]([\w-]+)\/([\w-]+)(?:\.git)?$/);
+    if (!match) {
+        throw new ValidationError(`Could not extract repository from shorthand: ${input}`);
+    }
+    const [, owner, repo] = match;
+    logger.debug('Parsed GitHub shorthand resource', {
+        input,
+        repo: `${owner}/${repo}`,
+        ref: version || gitSpec.ref,
+        path: gitSpec.path
+    });
+    return {
+        type: 'github-shorthand',
+        repo: `${owner}/${repo}`,
+        gitUrl: gitSpec.url,
+        ref: version || gitSpec.ref,
+        path: gitSpec.path
+    };
+}
+/**
+ * Parse a registry/OpenPackage resource name.
+ *
+ * Format: [@scope/]name[/path][@version]
+ */
+function parseRegistryResource(input) {
+    // Parse name[@version] and optional path
+    // Examples:
+    //   @hyericlee/essentials
+    //   @hyericlee/essentials/agents/designer
+    //   my-package@1.0.0
+    //   hyericlee/essentials (could be path or registry)
+    let name;
+    let version;
+    let path;
+    // Check for version specification
+    const atIndex = input.lastIndexOf('@');
+    if (atIndex > 0) {
+        // Has version
+        const beforeAt = input.slice(0, atIndex);
+        version = input.slice(atIndex + 1);
+        // Check if version contains path separator (invalid)
+        if (version.includes('/')) {
+            throw new ValidationError(`Version cannot be specified on sub-paths.\n\n` +
+                `Got: ${input}\n\n` +
+                `Valid format: package[@version][/path]\n` +
+                `Example: my-package@1.0.0/agents/designer`);
+        }
+        // Parse name and path from beforeAt
+        const segments = beforeAt.split('/');
+        if (beforeAt.startsWith('@')) {
+            // Scoped package: @scope/name[/path/...]
+            if (segments.length < 2) {
+                throw new ValidationError(`Invalid scoped package name: ${input}`);
+            }
+            name = segments.slice(0, 2).join('/');
+            path = segments.length > 2 ? segments.slice(2).join('/') : undefined;
+        }
+        else {
+            // Unscoped package: name[/path/...]
+            name = segments[0];
+            path = segments.length > 1 ? segments.slice(1).join('/') : undefined;
+        }
+    }
+    else {
+        // No version
+        const segments = input.split('/');
+        if (input.startsWith('@')) {
+            // Scoped package
+            if (segments.length < 2) {
+                throw new ValidationError(`Invalid scoped package name: ${input}`);
+            }
+            name = segments.slice(0, 2).join('/');
+            path = segments.length > 2 ? segments.slice(2).join('/') : undefined;
+        }
+        else {
+            // Unscoped package
+            name = segments[0];
+            path = segments.length > 1 ? segments.slice(1).join('/') : undefined;
+        }
+    }
+    logger.debug('Parsed registry resource', {
+        input,
+        name,
+        version,
+        path
+    });
+    return {
+        type: 'registry',
+        name,
+        version,
+        path
+    };
+}
+/**
+ * Check if input looks like a filesystem path.
+ */
+function looksLikePath(input) {
+    return (input.startsWith('/') ||
+        input.startsWith('./') ||
+        input.startsWith('../') ||
+        input.startsWith('~') ||
+        input === '.' ||
+        // Dot-directory paths: .opencode/, .cursor/, .claude/, etc.
+        (input.startsWith('.') && input.length > 1 && input.includes('/')) ||
+        (isAbsolute(input) && !input.includes('@')));
+}
+/**
+ * Check if input is unambiguously a path (not a registry name).
+ */
+function isUnambiguouslyPath(input) {
+    return (input.startsWith('/') ||
+        input.startsWith('./') ||
+        input.startsWith('../') ||
+        input.startsWith('~') ||
+        (input.startsWith('.') && input.length > 1 && input.includes('/')));
+}
+//# sourceMappingURL=resource-arg-parser.js.map

package/packages/core/dist/utils/resource-arg-parser.js.map

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

package/packages/core/dist/utils/root-file-extractor.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Utility for extracting and handling package-specific content markers
+ * for root files (AGENTS.md, CLAUDE.md, etc.).
+ *
+ * Marker format:
+ *   <!-- package: <package-name> --> ... <!-- -->
+ */
+/**
+ * Escape a string for safe insertion into a RegExp pattern.
+ */
+export declare function escapeRegExp(input: string): string;
+/** Build the literal open marker string for a package */
+export declare function buildOpenMarker(packageName: string): string;
+/** Constant close marker string */
+export declare const CLOSE_MARKER = "<!-- -->";
+/** Build a case-insensitive regex to match the open marker for a package */
+export declare function buildOpenMarkerRegex(packageName: string): RegExp;
+/** Case-insensitive regex to match any package open marker */
+export declare const OPEN_MARKER_ANY_REGEX: RegExp;
+/** Case-insensitive regex to match the close marker */
+export declare const CLOSE_MARKER_REGEX: RegExp;
+/**
+ * Global, non-greedy match between open/close markers, capturing package name and body
+ * Example: <!-- package: name --> ... <!-- -->
+ */
+export declare const FORMULA_SECTION_GLOBAL_REGEX: RegExp;
+/**
+ * Detect whether content includes a marker-wrapped section.
+ * If packageName is provided, ensures the open marker matches it.
+ */
+export declare function isMarkerWrappedContent(content: string, packageName?: string): boolean;
+/**
+ * Extract content for a specific package from AGENTS.md content.
+ *
+ * - Opening marker: <!-- package: <packageName> -->
+ * - Closing marker: <!-- --> (optionally allowing internal whitespace)
+ *
+ * Returns null if no matching section is found.
+ */
+export declare function extractPackageContentFromRootFile(content: string, packageName: string): string | null;
+/**
+ * Extract the section body for a specific package from marker-wrapped content.
+ * Supports markers in the format:
+ *   <!-- package: <name> --> ... <!-- -->
+ * Returns null if no section is found.
+ */
+export declare function extractPackageSection(content: string, packageName: string): {
+    sectionBody: string;
+} | null;
+/**
+ * Extract all package sections from a root file content.
+ * Returns a map of packageName → content.
+ */
+export declare function extractAllPackageSections(content: string): Map<string, string>;
+//# sourceMappingURL=root-file-extractor.d.ts.map

package/packages/core/dist/utils/root-file-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-file-extractor.d.ts","sourceRoot":"","sources":["../../src/utils/root-file-extractor.ts"],"names":[],"mappings":"AACA;;;;;;GAMG;AAEH;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,yDAAyD;AACzD,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED,mCAAmC;AACnC,eAAO,MAAM,YAAY,aAAa,CAAC;AAEvC,4EAA4E;AAC5E,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAGhE;AAED,8DAA8D;AAC9D,eAAO,MAAM,qBAAqB,QAAsC,CAAC;AAEzE,uDAAuD;AACvD,eAAO,MAAM,kBAAkB,QAAgB,CAAC;AAEhD;;;GAGG;AACH,eAAO,MAAM,4BAA4B,QAA2D,CAAC;AAErG;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAQrF;AAED;;;;;;;GAOG;AACH,wBAAgB,iCAAiC,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAiBrG;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,GAClB;IAAE,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAiBhC;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAkB9E"}

package/packages/core/dist/utils/root-file-extractor.js

@@ -0,0 +1,115 @@
+/**
+ * Utility for extracting and handling package-specific content markers
+ * for root files (AGENTS.md, CLAUDE.md, etc.).
+ *
+ * Marker format:
+ *   <!-- package: <package-name> --> ... <!-- -->
+ */
+/**
+ * Escape a string for safe insertion into a RegExp pattern.
+ */
+export function escapeRegExp(input) {
+    return input.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** Build the literal open marker string for a package */
+export function buildOpenMarker(packageName) {
+    return `<!-- package: ${packageName} -->`;
+}
+/** Constant close marker string */
+export const CLOSE_MARKER = '<!-- -->';
+/** Build a case-insensitive regex to match the open marker for a package */
+export function buildOpenMarkerRegex(packageName) {
+    const namePattern = escapeRegExp(packageName);
+    return new RegExp(`<!--\\s*package:\\s*${namePattern}\\s*-->`, 'i');
+}
+/** Case-insensitive regex to match any package open marker */
+export const OPEN_MARKER_ANY_REGEX = /<!--\s*package:\s*[^\s>]+?\s*-->/i;
+/** Case-insensitive regex to match the close marker */
+export const CLOSE_MARKER_REGEX = /<!--\s*-->/i;
+/**
+ * Global, non-greedy match between open/close markers, capturing package name and body
+ * Example: <!-- package: name --> ... <!-- -->
+ */
+export const FORMULA_SECTION_GLOBAL_REGEX = /<!--\s*package:\s*([^\s]+)\s*-->([\s\S]*?)<!--\s*-->/gi;
+/**
+ * Detect whether content includes a marker-wrapped section.
+ * If packageName is provided, ensures the open marker matches it.
+ */
+export function isMarkerWrappedContent(content, packageName) {
+    if (!content)
+        return false;
+    const hasClose = CLOSE_MARKER_REGEX.test(content);
+    if (!hasClose)
+        return false;
+    if (packageName) {
+        return buildOpenMarkerRegex(packageName).test(content);
+    }
+    return OPEN_MARKER_ANY_REGEX.test(content);
+}
+/**
+ * Extract content for a specific package from AGENTS.md content.
+ *
+ * - Opening marker: <!-- package: <packageName> -->
+ * - Closing marker: <!-- --> (optionally allowing internal whitespace)
+ *
+ * Returns null if no matching section is found.
+ */
+export function extractPackageContentFromRootFile(content, packageName) {
+    if (!content || !packageName)
+        return null;
+    const openRe = buildOpenMarkerRegex(packageName);
+    const closeRe = CLOSE_MARKER_REGEX;
+    const openMatch = openRe.exec(content);
+    if (!openMatch)
+        return null;
+    const startIndex = openMatch.index + openMatch[0].length;
+    const rest = content.slice(startIndex);
+    const closeMatch = closeRe.exec(rest);
+    if (!closeMatch)
+        return null;
+    const endIndexInRest = closeMatch.index; // relative to rest
+    const extracted = rest.slice(0, endIndexInRest);
+    return extracted.trim();
+}
+/**
+ * Extract the section body for a specific package from marker-wrapped content.
+ * Supports markers in the format:
+ *   <!-- package: <name> --> ... <!-- -->
+ * Returns null if no section is found.
+ */
+export function extractPackageSection(content, packageName) {
+    if (!content || !packageName)
+        return null;
+    const openRe = buildOpenMarkerRegex(packageName);
+    const closeRe = CLOSE_MARKER_REGEX;
+    const openMatch = openRe.exec(content);
+    if (!openMatch)
+        return null;
+    const startIndex = openMatch.index + openMatch[0].length;
+    const rest = content.slice(startIndex);
+    const closeMatch = closeRe.exec(rest);
+    if (!closeMatch)
+        return null;
+    const sectionBody = rest.slice(0, closeMatch.index).trim();
+    return { sectionBody };
+}
+/**
+ * Extract all package sections from a root file content.
+ * Returns a map of packageName → content.
+ */
+export function extractAllPackageSections(content) {
+    const sections = new Map();
+    if (!content) {
+        return sections;
+    }
+    // Clone the global regex to avoid cross-call lastIndex interference
+    const packagePattern = new RegExp(FORMULA_SECTION_GLOBAL_REGEX);
+    let match;
+    while ((match = packagePattern.exec(content)) !== null) {
+        const packageName = match[1].trim();
+        const sectionContent = match[2].trim();
+        sections.set(packageName, sectionContent);
+    }
+    return sections;
+}
+//# sourceMappingURL=root-file-extractor.js.map

package/packages/core/dist/utils/root-file-extractor.js.map

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

package/packages/core/dist/utils/root-file-merger.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Root File Content Merger Utility
+ * Handles marker-based content merging for root files (AGENTS.md, CLAUDE.md, etc.)
+ */
+/**
+ * Merge package-specific content into a root file while preserving all other content.
+ * Finds the package section between markers and replaces it, or appends if not found.
+ *
+ * @param existingContent - The current content of the root file (or empty string)
+ * @param packageName - Name of the package to merge
+ * @param newContent - Section body to insert between the markers (without markers)
+ * @returns Updated root file content with package section merged
+ */
+export declare function mergePackageContentIntoRootFile(existingContent: string, packageName: string, newContent: string): string;
+//# sourceMappingURL=root-file-merger.d.ts.map

package/packages/core/dist/utils/root-file-merger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-file-merger.d.ts","sourceRoot":"","sources":["../../src/utils/root-file-merger.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH;;;;;;;;GAQG;AACH,wBAAgB,+BAA+B,CAC7C,eAAe,EAAE,MAAM,EACvB,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,GACjB,MAAM,CAoDR"}

package/packages/core/dist/utils/root-file-merger.js

@@ -0,0 +1,57 @@
+/**
+ * Root File Content Merger Utility
+ * Handles marker-based content merging for root files (AGENTS.md, CLAUDE.md, etc.)
+ */
+import { buildOpenMarker, buildOpenMarkerRegex, CLOSE_MARKER, CLOSE_MARKER_REGEX } from './root-file-extractor.js';
+/**
+ * Merge package-specific content into a root file while preserving all other content.
+ * Finds the package section between markers and replaces it, or appends if not found.
+ *
+ * @param existingContent - The current content of the root file (or empty string)
+ * @param packageName - Name of the package to merge
+ * @param newContent - Section body to insert between the markers (without markers)
+ * @returns Updated root file content with package section merged
+ */
+export function mergePackageContentIntoRootFile(existingContent, packageName, newContent) {
+    if (!packageName) {
+        throw new Error('Package name is required for merging');
+    }
+    const openMarker = buildOpenMarker(packageName);
+    const closeMarker = CLOSE_MARKER;
+    // Create regex to find existing package section
+    const openRe = buildOpenMarkerRegex(packageName);
+    const closeRe = CLOSE_MARKER_REGEX;
+    const openMatch = openRe.exec(existingContent);
+    if (!openMatch) {
+        // Package section doesn't exist - append it
+        const separator = existingContent.trim() ? '\n\n' : '';
+        return existingContent.trim() + separator + openMarker + '\n' + newContent.trim() + '\n' + closeMarker + '\n';
+    }
+    // Package section exists - check if it already has the correct content
+    const beforeSection = existingContent.substring(0, openMatch.index);
+    const afterMarkerIndex = openMatch.index + openMatch[0].length;
+    const restContent = existingContent.substring(afterMarkerIndex);
+    const closeMatch = closeRe.exec(restContent);
+    if (!closeMatch) {
+        // Malformed - missing closing marker, append new section at end
+        const separator = existingContent.trim() ? '\n\n' : '';
+        return existingContent.trim() + separator + openMarker + '\n' + newContent.trim() + '\n' + closeMarker + '\n';
+    }
+    // Extract the existing section content
+    const existingSectionBody = restContent.substring(0, closeMatch.index).trim();
+    const afterCloseMarkerIndex = closeMatch.index + closeMatch[0].length;
+    const afterSection = restContent.substring(afterCloseMarkerIndex);
+    // Check if the existing section already has the correct content and marker
+    // Use component-wise comparison to avoid issues with whitespace formatting differences
+    const existingOpenMarker = openMatch[0];
+    const hasCorrectMarker = existingOpenMarker === openMarker;
+    const hasCorrectContent = existingSectionBody === newContent.trim();
+    const hasCloseMarker = true; // We already verified closeMatch exists
+    if (hasCorrectMarker && hasCorrectContent && hasCloseMarker) {
+        // Existing section is already correct, return unchanged
+        return existingContent;
+    }
+    // Replace the section content
+    return beforeSection + openMarker + '\n' + newContent.trim() + '\n' + closeMarker + afterSection;
+}
+//# sourceMappingURL=root-file-merger.js.map

package/packages/core/dist/utils/root-file-merger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-file-merger.js","sourceRoot":"","sources":["../../src/utils/root-file-merger.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAEnH;;;;;;;;GAQG;AACH,MAAM,UAAU,+BAA+B,CAC7C,eAAuB,EACvB,WAAmB,EACnB,UAAkB;IAElB,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;IAC1D,CAAC;IAED,MAAM,UAAU,GAAG,eAAe,CAAC,WAAW,CAAC,CAAC;IAChD,MAAM,WAAW,GAAG,YAAY,CAAC;IAEjC,gDAAgD;IAChD,MAAM,MAAM,GAAG,oBAAoB,CAAC,WAAW,CAAC,CAAC;IACjD,MAAM,OAAO,GAAG,kBAAkB,CAAC;IAEnC,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;IAE/C,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,4CAA4C;QAC5C,MAAM,SAAS,GAAG,eAAe,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;QACvD,OAAO,eAAe,CAAC,IAAI,EAAE,GAAG,SAAS,GAAG,UAAU,GAAG,IAAI,GAAG,UAAU,CAAC,IAAI,EAAE,GAAG,IAAI,GAAG,WAAW,GAAG,IAAI,CAAC;IAChH,CAAC;IAED,uEAAuE;IACvE,MAAM,aAAa,GAAG,eAAe,CAAC,SAAS,CAAC,CAAC,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC;IACpE,MAAM,gBAAgB,GAAG,SAAS,CAAC,KAAK,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IAC/D,MAAM,WAAW,GAAG,eAAe,CAAC,SAAS,CAAC,gBAAgB,CAAC,CAAC;IAEhE,MAAM,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAE7C,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,gEAAgE;QAChE,MAAM,SAAS,GAAG,eAAe,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;QACvD,OAAO,eAAe,CAAC,IAAI,EAAE,GAAG,SAAS,GAAG,UAAU,GAAG,IAAI,GAAG,UAAU,CAAC,IAAI,EAAE,GAAG,IAAI,GAAG,WAAW,GAAG,IAAI,CAAC;IAChH,CAAC;IAED,uCAAuC;IACvC,MAAM,mBAAmB,GAAG,WAAW,CAAC,SAAS,CAAC,CAAC,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC;IAC9E,MAAM,qBAAqB,GAAG,UAAU,CAAC,KAAK,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IACtE,MAAM,YAAY,GAAG,WAAW,CAAC,SAAS,CAAC,qBAAqB,CAAC,CAAC;IAElE,2EAA2E;IAC3E,uFAAuF;IACvF,MAAM,kBAAkB,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;IACxC,MAAM,gBAAgB,GAAG,kBAAkB,KAAK,UAAU,CAAC;IAC3D,MAAM,iBAAiB,GAAG,mBAAmB,KAAK,UAAU,CAAC,IAAI,EAAE,CAAC;IACpE,MAAM,cAAc,GAAG,IAAI,CAAC,CAAC,wCAAwC;IAErE,IAAI,gBAAgB,IAAI,iBAAiB,IAAI,cAAc,EAAE,CAAC;QAC5D,wDAAwD;QACxD,OAAO,eAAe,CAAC;IACzB,CAAC;IAED,8BAA8B;IAC9B,OAAO,aAAa,GAAG,UAAU,GAAG,IAAI,GAAG,UAAU,CAAC,IAAI,EAAE,GAAG,IAAI,GAAG,WAAW,GAAG,YAAY,CAAC;AACnG,CAAC"}

package/packages/core/dist/utils/source-operation-arguments.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Options for resolving source operation arguments.
+ */
+export interface SourceOperationOptions {
+    /** Command name for error messages ('add' | 'remove') */
+    command: 'add' | 'remove';
+    /** Whether to check workspace root path in addition to filesystem path (for remove) */
+    checkWorkspaceRoot?: boolean;
+}
+/**
+ * Resolved source operation result.
+ */
+export interface ResolvedSourceOperation {
+    /** Package name (null = workspace root, string = specific package) */
+    resolvedPackageName: string | null;
+    /** Path to operate on */
+    resolvedPath: string;
+}
+/**
+ * Resolve source operation arguments to determine package name and operation path.
+ *
+ * This shared utility handles argument resolution for both add and remove commands:
+ * - For add: packageName from --to option, pathArg is source path to add
+ * - For remove: packageName from --from option, pathArg is target path to remove
+ *
+ * @param cwd - Current working directory
+ * @param packageName - Package name from --to/--from option (undefined = workspace root)
+ * @param pathArg - Path argument from command line
+ * @param options - Command-specific options
+ * @returns Resolved package name and path
+ *
+ * @example
+ * // Add command: opkg add ./file.md --to my-package
+ * const result = await resolveSourceOperationArguments(
+ *   cwd, 'my-package', './file.md', { command: 'add' }
+ * );
+ * // => { resolvedPackageName: 'my-package', resolvedPath: './file.md' }
+ *
+ * @example
+ * // Remove command: opkg remove agents/my-agent
+ * const result = await resolveSourceOperationArguments(
+ *   cwd, undefined, 'agents/my-agent', { command: 'remove', checkWorkspaceRoot: true }
+ * );
+ * // Checks both ./agents/my-agent AND .openpackage/agents/my-agent
+ * // => { resolvedPackageName: null, resolvedPath: 'agents/my-agent' }
+ */
+export declare function resolveSourceOperationArguments(cwd: string, packageName: string | undefined, pathArg: string | undefined, options: SourceOperationOptions): Promise<ResolvedSourceOperation>;
+//# sourceMappingURL=source-operation-arguments.d.ts.map

package/packages/core/dist/utils/source-operation-arguments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-operation-arguments.d.ts","sourceRoot":"","sources":["../../src/utils/source-operation-arguments.ts"],"names":[],"mappings":"AAKA;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,yDAAyD;IACzD,OAAO,EAAE,KAAK,GAAG,QAAQ,CAAC;IAC1B,uFAAuF;IACvF,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,sEAAsE;IACtE,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,yBAAyB;IACzB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,+BAA+B,CACnD,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,uBAAuB,CAAC,CA0ClC"}

package/packages/core/dist/utils/source-operation-arguments.js

@@ -0,0 +1,66 @@
+import { resolve as resolvePath, join } from 'path';
+import { exists } from './fs.js';
+import { getLocalOpenPackageDir } from './paths.js';
+/**
+ * Resolve source operation arguments to determine package name and operation path.
+ *
+ * This shared utility handles argument resolution for both add and remove commands:
+ * - For add: packageName from --to option, pathArg is source path to add
+ * - For remove: packageName from --from option, pathArg is target path to remove
+ *
+ * @param cwd - Current working directory
+ * @param packageName - Package name from --to/--from option (undefined = workspace root)
+ * @param pathArg - Path argument from command line
+ * @param options - Command-specific options
+ * @returns Resolved package name and path
+ *
+ * @example
+ * // Add command: opkg add ./file.md --to my-package
+ * const result = await resolveSourceOperationArguments(
+ *   cwd, 'my-package', './file.md', { command: 'add' }
+ * );
+ * // => { resolvedPackageName: 'my-package', resolvedPath: './file.md' }
+ *
+ * @example
+ * // Remove command: opkg remove agents/my-agent
+ * const result = await resolveSourceOperationArguments(
+ *   cwd, undefined, 'agents/my-agent', { command: 'remove', checkWorkspaceRoot: true }
+ * );
+ * // Checks both ./agents/my-agent AND .openpackage/agents/my-agent
+ * // => { resolvedPackageName: null, resolvedPath: 'agents/my-agent' }
+ */
+export async function resolveSourceOperationArguments(cwd, packageName, pathArg, options) {
+    const { command, checkWorkspaceRoot = false } = options;
+    const flagName = command === 'add' ? '--to' : '--from';
+    // Two arguments provided: explicit package name + path
+    if (packageName && pathArg) {
+        return { resolvedPackageName: packageName, resolvedPath: pathArg };
+    }
+    // One argument provided
+    const singleArg = packageName || pathArg;
+    if (!singleArg) {
+        throw new Error(`Path argument is required for ${command}.`);
+    }
+    // Check if single arg is a valid path
+    const absPath = resolvePath(cwd, singleArg);
+    let pathExists = await exists(absPath);
+    // For remove command, also check workspace root path
+    if (!pathExists && checkWorkspaceRoot) {
+        const openpackageDir = getLocalOpenPackageDir(cwd);
+        const workspaceRootPath = join(openpackageDir, singleArg);
+        pathExists = await exists(workspaceRootPath);
+    }
+    if (pathExists) {
+        // It's a valid path → operate on workspace root
+        return { resolvedPackageName: null, resolvedPath: singleArg };
+    }
+    // Path doesn't exist. For remove, pass through so the pipeline can try dependency resolution.
+    // For add, this would have failed earlier. Only remove uses checkWorkspaceRoot.
+    if (checkWorkspaceRoot && command === 'remove') {
+        return { resolvedPackageName: null, resolvedPath: singleArg };
+    }
+    // Not a valid path → treat as package name (error will be thrown later)
+    throw new Error(`Path '${singleArg}' not found.\n\n` +
+        `If you meant to specify a package name, use: opkg ${command} <path> ${flagName} ${singleArg}`);
+}
+//# sourceMappingURL=source-operation-arguments.js.map

package/packages/core/dist/utils/source-operation-arguments.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-operation-arguments.js","sourceRoot":"","sources":["../../src/utils/source-operation-arguments.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAEpD,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAsBpD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,CAAC,KAAK,UAAU,+BAA+B,CACnD,GAAW,EACX,WAA+B,EAC/B,OAA2B,EAC3B,OAA+B;IAE/B,MAAM,EAAE,OAAO,EAAE,kBAAkB,GAAG,KAAK,EAAE,GAAG,OAAO,CAAC;IACxD,MAAM,QAAQ,GAAG,OAAO,KAAK,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC;IAEvD,uDAAuD;IACvD,IAAI,WAAW,IAAI,OAAO,EAAE,CAAC;QAC3B,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC;IACrE,CAAC;IAED,wBAAwB;IACxB,MAAM,SAAS,GAAG,WAAW,IAAI,OAAO,CAAC;IACzC,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,iCAAiC,OAAO,GAAG,CAAC,CAAC;IAC/D,CAAC;IAED,sCAAsC;IACtC,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;IAC5C,IAAI,UAAU,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,CAAC;IAEvC,qDAAqD;IACrD,IAAI,CAAC,UAAU,IAAI,kBAAkB,EAAE,CAAC;QACtC,MAAM,cAAc,GAAG,sBAAsB,CAAC,GAAG,CAAC,CAAC;QACnD,MAAM,iBAAiB,GAAG,IAAI,CAAC,cAAc,EAAE,SAAS,CAAC,CAAC;QAC1D,UAAU,GAAG,MAAM,MAAM,CAAC,iBAAiB,CAAC,CAAC;IAC/C,CAAC;IAED,IAAI,UAAU,EAAE,CAAC;QACf,gDAAgD;QAChD,OAAO,EAAE,mBAAmB,EAAE,IAAI,EAAE,YAAY,EAAE,SAAS,EAAE,CAAC;IAChE,CAAC;IAED,8FAA8F;IAC9F,gFAAgF;IAChF,IAAI,kBAAkB,IAAI,OAAO,KAAK,QAAQ,EAAE,CAAC;QAC/C,OAAO,EAAE,mBAAmB,EAAE,IAAI,EAAE,YAAY,EAAE,SAAS,EAAE,CAAC;IAChE,CAAC;IAED,wEAAwE;IACxE,MAAM,IAAI,KAAK,CACb,SAAS,SAAS,kBAAkB;QACpC,qDAAqD,OAAO,WAAW,QAAQ,IAAI,SAAS,EAAE,CAC/F,CAAC;AACJ,CAAC"}