@jackwener/opencli 1.6.4 → 1.6.6

package/dist/clis/zsxq/topic.test.js

@@ -1,5 +1,5 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
-import { getRegistry } from '../../src/registry.js';
+import { getRegistry } from '@jackwener/opencli/registry';
 import './topic.js';
 describe('zsxq topic command', () => {
     beforeEach(() => {

package/dist/clis/zsxq/topics.js

@@ -1,4 +1,4 @@
-import { cli, Strategy } from '../../src/registry.js';
+import { cli, Strategy } from '@jackwener/opencli/registry';
 import { getActiveGroupId, ensureZsxqAuth, ensureZsxqPage, fetchFirstJson, getTopicsFromResponse, toTopicRow, } from './utils.js';
 cli({
     site: 'zsxq',

package/dist/clis/zsxq/topics.test.js

@@ -1,5 +1,5 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
-import { getRegistry } from '../../src/registry.js';
+import { getRegistry } from '@jackwener/opencli/registry';
 import './topics.js';
 describe('zsxq topics command', () => {
     beforeEach(() => {

package/dist/clis/zsxq/utils.d.ts

@@ -1,4 +1,4 @@
-import type { IPage } from '../../src/types.js';
+import type { IPage } from '@jackwener/opencli/types';
 export interface ZsxqUser {
     user_id?: number;
     name?: string;

package/dist/clis/zsxq/utils.js

@@ -1,4 +1,4 @@
-import { ArgumentError, AuthRequiredError, CliError } from '../../src/errors.js';
+import { ArgumentError, AuthRequiredError, CliError } from '@jackwener/opencli/errors';
 const SITE_DOMAIN = 'wx.zsxq.com';
 const SITE_URL = 'https://wx.zsxq.com';
 function asRecord(value) {

package/dist/src/discovery.d.ts

@@ -14,12 +14,12 @@ export declare const USER_CLIS_DIR: string;
 /** Plugins directory: ~/.opencli/plugins/ */
 export declare const PLUGINS_DIR: string;
 /**
- * Create runtime shim files under ~/.opencli so user CLIs can keep
- * importing ../../registry(.js), ../../errors(.js), etc.
+ * Ensure ~/.opencli/node_modules/@jackwener/opencli symlink exists so that
+ * user CLIs in ~/.opencli/clis/ can `import { cli } from '@jackwener/opencli/registry'`.
  *
- * Adapters use relative imports like `../../registry.js` which, from
- * ~/.opencli/clis/<site>/<cmd>.js, resolve to ~/.opencli/registry.js.
- * We create shim files that re-export from the installed opencli runtime.
+ * This is the sole resolution mechanism — adapters use package exports
+ * (e.g. `@jackwener/opencli/registry`, `@jackwener/opencli/errors`) and
+ * Node.js resolves them through this symlink.
  */
 export declare function ensureUserCliCompatShims(baseDir?: string): Promise<void>;
 /**

package/dist/src/discovery.js

@@ -43,88 +43,32 @@ function findPackageRoot() {
     }
     return dir;
 }
-function resolveHostRuntimeModulePath(moduleName) {
-    const runtimeDir = path.dirname(fileURLToPath(import.meta.url));
-    for (const ext of ['.js', '.ts']) {
-        const candidate = path.join(runtimeDir, `${moduleName}${ext}`);
-        if (fs.existsSync(candidate))
-            return candidate;
-    }
-    return path.join(runtimeDir, `${moduleName}.js`);
-}
-async function writeCompatShimIfNeeded(filePath, content) {
-    try {
-        const existing = await fs.promises.readFile(filePath, 'utf-8');
-        if (existing === content)
-            return;
-    }
-    catch {
-        // Fall through to write missing shim
-    }
-    await fs.promises.writeFile(filePath, content, 'utf-8');
-}
 /**
- * Create runtime shim files under ~/.opencli so user CLIs can keep
- * importing ../../registry(.js), ../../errors(.js), etc.
+ * Ensure ~/.opencli/node_modules/@jackwener/opencli symlink exists so that
+ * user CLIs in ~/.opencli/clis/ can `import { cli } from '@jackwener/opencli/registry'`.
  *
- * Adapters use relative imports like `../../registry.js` which, from
- * ~/.opencli/clis/<site>/<cmd>.js, resolve to ~/.opencli/registry.js.
- * We create shim files that re-export from the installed opencli runtime.
+ * This is the sole resolution mechanism — adapters use package exports
+ * (e.g. `@jackwener/opencli/registry`, `@jackwener/opencli/errors`) and
+ * Node.js resolves them through this symlink.
  */
 export async function ensureUserCliCompatShims(baseDir = USER_OPENCLI_DIR) {
     await fs.promises.mkdir(baseDir, { recursive: true });
-    // Map of shim name → runtime module name (resolved via resolveHostRuntimeModulePath)
-    const rootShims = [
-        ['registry', 'registry-api'],
-        ['errors', 'errors'],
-        ['types', 'types'],
-        ['utils', 'utils'],
-        ['logger', 'logger'],
-        ['launcher', 'launcher'],
-    ];
-    // Subdirectory shims: [subdir, filename, runtime module path relative to src/]
-    const subdirShims = [
-        ['browser', 'cdp', 'browser/cdp'],
-        ['browser', 'page', 'browser/page'],
-        ['browser', 'utils', 'browser/utils'],
-        ['download', 'index', 'download/index'],
-        ['download', 'article-download', 'download/article-download'],
-        ['download', 'media-download', 'download/media-download'],
-        ['download', 'progress', 'download/progress'],
-        ['pipeline', 'index', 'pipeline/index'],
-    ];
-    const writes = [];
-    // Root-level shims (both with and without .js extension)
-    // Also generate src/ shims: adapters import ../../src/registry.js etc., which
-    // resolve to ~/.opencli/src/registry.js when running from ~/.opencli/clis/<site>/
-    const srcDir = path.join(baseDir, 'src');
-    await fs.promises.mkdir(srcDir, { recursive: true });
-    for (const [shimName, moduleName] of rootShims) {
-        const url = pathToFileURL(resolveHostRuntimeModulePath(moduleName)).href;
-        const content = `export * from '${url}';\n`;
-        writes.push(writeCompatShimIfNeeded(path.join(baseDir, shimName), content));
-        writes.push(writeCompatShimIfNeeded(path.join(baseDir, `${shimName}.js`), content));
-        writes.push(writeCompatShimIfNeeded(path.join(srcDir, `${shimName}.js`), content));
+    // package.json for ESM resolution in ~/.opencli/
+    const pkgJsonPath = path.join(baseDir, 'package.json');
+    const pkgJsonContent = `${JSON.stringify({ name: 'opencli-user-runtime', private: true, type: 'module' }, null, 2)}\n`;
+    try {
+        const existing = await fs.promises.readFile(pkgJsonPath, 'utf-8');
+        if (existing !== pkgJsonContent)
+            await fs.promises.writeFile(pkgJsonPath, pkgJsonContent, 'utf-8');
     }
-    // Subdirectory shims
-    for (const [subdir, filename, runtimePath] of subdirShims) {
-        const dir = path.join(baseDir, subdir);
-        await fs.promises.mkdir(dir, { recursive: true });
-        const url = pathToFileURL(resolveHostRuntimeModulePath(runtimePath)).href;
-        const content = `export * from '${url}';\n`;
-        writes.push(writeCompatShimIfNeeded(path.join(dir, `${filename}.js`), content));
+    catch {
+        await fs.promises.writeFile(pkgJsonPath, pkgJsonContent, 'utf-8');
     }
-    // package.json for ESM resolution
-    writes.push(writeCompatShimIfNeeded(path.join(baseDir, 'package.json'), `${JSON.stringify({ name: 'opencli-user-runtime', private: true, type: 'module' }, null, 2)}\n`));
-    await Promise.all(writes);
-    // Create node_modules/@jackwener/opencli symlink so user TS CLIs can import
-    // from '@jackwener/opencli/registry' (the package export).
-    // This is needed because ~/.opencli/clis/ is outside opencli's node_modules tree.
+    // Create node_modules/@jackwener/opencli symlink pointing to the installed package root.
     const opencliRoot = findPackageRoot();
     const symlinkDir = path.join(baseDir, 'node_modules', '@jackwener');
     const symlinkPath = path.join(symlinkDir, 'opencli');
     try {
-        // Only recreate if symlink is missing or points to wrong target
         let needsUpdate = true;
         try {
             const existing = await fs.promises.readlink(symlinkPath);
@@ -135,14 +79,15 @@ export async function ensureUserCliCompatShims(baseDir = USER_OPENCLI_DIR) {
         if (needsUpdate) {
             await fs.promises.mkdir(symlinkDir, { recursive: true });
             try {
-                await fs.promises.unlink(symlinkPath);
+                await fs.promises.rm(symlinkPath, { recursive: true, force: true });
             }
             catch { /* doesn't exist */ }
-            await fs.promises.symlink(opencliRoot, symlinkPath, 'dir');
+            const symlinkType = process.platform === 'win32' ? 'junction' : 'dir';
+            await fs.promises.symlink(opencliRoot, symlinkPath, symlinkType);
         }
     }
-    catch {
-        // Non-fatal: npm-linked installs or permission issues may prevent this
+    catch (err) {
+        log.warn(`Could not create symlink at ${symlinkPath}: ${getErrorMessage(err)}`);
     }
 }
 const ADAPTER_MANIFEST_PATH = path.join(USER_OPENCLI_DIR, 'adapter-manifest.json');

package/dist/src/engine.test.js

@@ -71,7 +71,7 @@ cli({
             await fs.promises.rm(tempBuildRoot, { recursive: true, force: true });
         }
     });
-    it('loads legacy user TS CLI modules via compatibility shims', async () => {
+    it('loads user CLI modules via package exports symlink', async () => {
         const tempOpencliRoot = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'opencli-user-clis-'));
         const userClisDir = path.join(tempOpencliRoot, 'clis');
         const siteDir = path.join(userClisDir, 'legacy-site');
@@ -80,8 +80,9 @@ cli({
             await ensureUserCliCompatShims(tempOpencliRoot);
             await fs.promises.mkdir(siteDir, { recursive: true });
             await fs.promises.writeFile(commandPath, `
-import { cli, Strategy } from '../../registry';
-import { CommandExecutionError } from '../../errors';
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { CommandExecutionError } from '@jackwener/opencli/errors';
+import { htmlToMarkdown } from '@jackwener/opencli/utils';
 
 cli({
   site: 'legacy-site',
@@ -89,13 +90,13 @@ cli({
   description: 'hello command',
   strategy: Strategy.PUBLIC,
   browser: false,
-  func: async () => [{ ok: true, errorName: new CommandExecutionError('boom').name }],
+  func: async () => [{ ok: true, errorName: new CommandExecutionError('boom').name, markdown: htmlToMarkdown('<p>hello</p>') }],
 });
 `);
             await discoverClis(userClisDir);
             const cmd = getRegistry().get('legacy-site/hello');
             expect(cmd).toBeDefined();
-            await expect(executeCommand(cmd, {})).resolves.toEqual([{ ok: true, errorName: 'CommandExecutionError' }]);
+            await expect(executeCommand(cmd, {})).resolves.toEqual([{ ok: true, errorName: 'CommandExecutionError', markdown: 'hello' }]);
         }
         finally {
             await fs.promises.rm(tempOpencliRoot, { recursive: true, force: true });

package/dist/src/logger.d.ts

@@ -7,6 +7,10 @@
 export declare const log: {
     /** Informational message (always shown) */
     info(msg: string): void;
+    /** Lightweight status line for adapter progress updates */
+    status(msg: string): void;
+    /** Positive completion/status line without the heavier info prefix */
+    success(msg: string): void;
     /** Warning (always shown) */
     warn(msg: string): void;
     /** Error (always shown) */

package/dist/src/logger.js

@@ -16,6 +16,14 @@ export const log = {
     info(msg) {
         process.stderr.write(`${chalk.blue('ℹ')}  ${msg}\n`);
     },
+    /** Lightweight status line for adapter progress updates */
+    status(msg) {
+        process.stderr.write(`${chalk.dim(msg)}\n`);
+    },
+    /** Positive completion/status line without the heavier info prefix */
+    success(msg) {
+        process.stderr.write(`${chalk.green(msg)}\n`);
+    },
     /** Warning (always shown) */
     warn(msg) {
         process.stderr.write(`${chalk.yellow('⚠')}  ${msg}\n`);

package/dist/src/package-exports.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/package-exports.test.js

@@ -0,0 +1,112 @@
+/**
+ * Regression tests for package exports.
+ *
+ * Ensures adapter files use @jackwener/opencli/... package imports
+ * (not fragile relative paths) and that all declared exports resolve
+ * to real files. Prevents regressions like #788 / #791.
+ */
+import { describe, it, expect } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { builtinModules } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import ts from 'typescript';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, '..');
+const CLIS_DIR = path.join(ROOT, 'clis');
+/** Recursively collect all .ts files in a directory. */
+function collectTsFiles(dir, opts) {
+    const results = [];
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            results.push(...collectTsFiles(full, opts));
+        }
+        else if (entry.name.endsWith('.ts') && !entry.name.endsWith('.d.ts')) {
+            if (opts?.excludeTests && (entry.name.endsWith('.test.ts') || entry.name === 'test-utils.ts'))
+                continue;
+            results.push(full);
+        }
+    }
+    return results;
+}
+const ALLOWED_BARE_IMPORTS = new Set([
+    '@jackwener/opencli',
+    ...builtinModules.flatMap((name) => name.startsWith('node:')
+        ? [name, name.slice(5)]
+        : [name, `node:${name}`]),
+]);
+function isAllowedImport(specifier) {
+    return specifier.startsWith('./')
+        || specifier.startsWith('../')
+        || specifier.startsWith('/')
+        || specifier.startsWith('@jackwener/opencli/')
+        || ALLOWED_BARE_IMPORTS.has(specifier);
+}
+/** Forbidden relative import patterns that should have been replaced.
+ * Uses (?:\.\./)+ to catch any depth of ../ traversal.
+ * Covers: import/export from, vi.mock(), vi.importActual(). */
+const FORBIDDEN_PATTERNS = [
+    /(?:from|mock|importActual)\s*\(?['"](?:\.\.\/)+src\//,
+    /(?:from|mock|importActual)\s*\(?['"](?:\.\.\/)+browser\//,
+    /(?:from|mock|importActual)\s*\(?['"](?:\.\.\/)+download\//,
+    /(?:from|mock|importActual)\s*\(?['"](?:\.\.\/)+pipeline\//,
+];
+describe('adapter imports use package exports', () => {
+    const adapterFiles = collectTsFiles(CLIS_DIR);
+    const runtimeAdapterFiles = collectTsFiles(CLIS_DIR, { excludeTests: true });
+    it('found adapter files to check', () => {
+        expect(adapterFiles.length).toBeGreaterThan(100);
+    });
+    it('no adapter uses relative imports to src/, browser/, download/, or pipeline/', () => {
+        const violations = [];
+        for (const file of adapterFiles) {
+            const content = fs.readFileSync(file, 'utf-8');
+            for (const pattern of FORBIDDEN_PATTERNS) {
+                if (pattern.test(content)) {
+                    const rel = path.relative(ROOT, file);
+                    const match = content.match(pattern)?.[0];
+                    violations.push(`${rel}: ${match}`);
+                }
+            }
+        }
+        expect(violations).toEqual([]);
+    });
+    it('non-test adapters only import node builtins, relative modules, or opencli public APIs', () => {
+        const violations = [];
+        for (const file of runtimeAdapterFiles) {
+            const source = fs.readFileSync(file, 'utf-8');
+            const module = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+            for (const stmt of module.statements) {
+                if (!ts.isImportDeclaration(stmt) && !ts.isExportDeclaration(stmt))
+                    continue;
+                const specifier = stmt.moduleSpecifier?.getText(module).slice(1, -1);
+                if (specifier && !isAllowedImport(specifier)) {
+                    violations.push({
+                        file: path.relative(ROOT, file),
+                        specifier,
+                    });
+                }
+            }
+        }
+        expect(violations).toEqual([]);
+    });
+});
+describe('package.json exports resolve to real files', () => {
+    const pkgJson = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf-8'));
+    const exports = pkgJson.exports;
+    it('has exports defined', () => {
+        expect(Object.keys(exports).length).toBeGreaterThan(5);
+    });
+    for (const [exportPath, target] of Object.entries(exports)) {
+        it(`export "${exportPath}" → ${target} has a source file`, () => {
+            // Export targets point to dist/ (compiled). Verify the source .ts exists.
+            // dist/src/foo.js → src/foo.ts
+            const sourcePath = target
+                .replace(/^\.\/dist\//, './')
+                .replace(/\.js$/, '.ts');
+            const fullPath = path.join(ROOT, sourcePath);
+            expect(fs.existsSync(fullPath), `Missing source: ${sourcePath}`).toBe(true);
+        });
+    }
+});

package/dist/src/registry-api.d.ts

@@ -7,7 +7,7 @@
  * plugins are dynamically imported during discoverPlugins().
  */
 export { cli, Strategy, getRegistry, fullName, registerCommand } from './registry.js';
-export type { CliCommand, Arg, CliOptions } from './registry.js';
+export type { CliCommand, Arg, CliOptions, CommandArgs } from './registry.js';
 export type { IPage } from './types.js';
 export { onStartup, onBeforeExecute, onAfterExecute } from './hooks.js';
 export type { HookFn, HookContext, HookName } from './hooks.js';

package/dist/src/utils.d.ts

@@ -1,6 +1,7 @@
 /**
  * Shared utility functions used across the codebase.
  */
+import TurndownService from 'turndown';
 /** Type guard: checks if a value is a non-null, non-array object. */
 export declare function isRecord(value: unknown): value is Record<string, unknown>;
 /** Simple async concurrency limiter. */
@@ -9,3 +10,5 @@ export declare function mapConcurrent<T, R>(items: T[], limit: number, fn: (item
 export declare function sleep(ms: number): Promise<void>;
 /** Save a base64-encoded string to a file, creating parent directories as needed. */
 export declare function saveBase64ToFile(base64: string, filePath: string): Promise<void>;
+export declare function createMarkdownConverter(configure?: (td: TurndownService) => void): TurndownService;
+export declare function htmlToMarkdown(value: string, configure?: (td: TurndownService) => void): string;

package/dist/src/utils.js

@@ -3,6 +3,7 @@
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import TurndownService from 'turndown';
 /** Type guard: checks if a value is a non-null, non-array object. */
 export function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -31,3 +32,24 @@ export async function saveBase64ToFile(base64, filePath) {
     await fs.promises.mkdir(dir, { recursive: true });
     await fs.promises.writeFile(filePath, Buffer.from(base64, 'base64'));
 }
+export function createMarkdownConverter(configure) {
+    const td = new TurndownService({
+        headingStyle: 'atx',
+        codeBlockStyle: 'fenced',
+        bulletListMarker: '-',
+    });
+    td.addRule('linebreak', {
+        filter: 'br',
+        replacement: () => '\n',
+    });
+    if (configure)
+        configure(td);
+    return td;
+}
+export function htmlToMarkdown(value, configure) {
+    return createMarkdownConverter(configure).turndown(value || '')
+        .replace(/\u00a0/g, ' ')
+        .replace(/\n{4,}/g, '\n\n\n')
+        .replace(/[ \t]+$/gm, '')
+        .trim();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jackwener/opencli",
-  "version": "1.6.4",
+  "version": "1.6.6",
   "publishConfig": {
     "access": "public"
   },
@@ -15,21 +15,25 @@
   },
   "exports": {
     ".": "./dist/src/main.js",
-    "./registry": "./dist/src/registry-api.js"
+    "./registry": "./dist/src/registry-api.js",
+    "./errors": "./dist/src/errors.js",
+    "./types": "./dist/src/types.js",
+    "./utils": "./dist/src/utils.js",
+    "./logger": "./dist/src/logger.js",
+    "./launcher": "./dist/src/launcher.js",
+    "./browser/cdp": "./dist/src/browser/cdp.js",
+    "./browser/page": "./dist/src/browser/page.js",
+    "./browser/utils": "./dist/src/browser/utils.js",
+    "./download": "./dist/src/download/index.js",
+    "./download/article-download": "./dist/src/download/article-download.js",
+    "./download/media-download": "./dist/src/download/media-download.js",
+    "./download/progress": "./dist/src/download/progress.js",
+    "./pipeline": "./dist/src/pipeline/index.js"
   },
   "files": [
     "dist/src/",
     "dist/clis/",
     "dist/cli-manifest.json",
-    "dist/registry.*",
-    "dist/errors.*",
-    "dist/types.*",
-    "dist/utils.*",
-    "dist/logger.*",
-    "dist/launcher.*",
-    "dist/browser/",
-    "dist/download/",
-    "dist/pipeline/",
     "scripts/",
     "README.md",
     "LICENSE"

package/dist/browser/cdp.d.ts

@@ -1 +0,0 @@
-export * from '../src/browser/cdp.js';

package/dist/browser/cdp.js

@@ -1,2 +0,0 @@
-// Shim: re-exports from src/browser/ for adapter imports
-export * from '../src/browser/cdp.js';

package/dist/browser/page.d.ts

@@ -1 +0,0 @@
-export * from '../src/browser/page.js';

package/dist/browser/page.js

@@ -1,2 +0,0 @@
-// Shim: re-exports from src/browser/ for adapter imports
-export * from '../src/browser/page.js';

package/dist/browser/utils.d.ts

@@ -1 +0,0 @@
-export * from '../src/browser/utils.js';

package/dist/browser/utils.js

@@ -1,2 +0,0 @@
-// Shim: re-exports from src/browser/ for adapter imports
-export * from '../src/browser/utils.js';

package/dist/download/article-download.d.ts

@@ -1 +0,0 @@
-export * from '../src/download/article-download.js';

package/dist/download/article-download.js

@@ -1,2 +0,0 @@
-// Shim: re-exports from src/download/ for adapter imports
-export * from '../src/download/article-download.js';

package/dist/download/index.d.ts

@@ -1 +0,0 @@
-export * from '../src/download/index.js';

package/dist/download/index.js

@@ -1,2 +0,0 @@
-// Shim: re-exports from src/download/ for adapter imports
-export * from '../src/download/index.js';

package/dist/download/media-download.d.ts

@@ -1 +0,0 @@
-export * from '../src/download/media-download.js';

package/dist/download/media-download.js

@@ -1,2 +0,0 @@
-// Shim: re-exports from src/download/ for adapter imports
-export * from '../src/download/media-download.js';

package/dist/download/progress.d.ts

@@ -1 +0,0 @@
-export * from '../src/download/progress.js';

package/dist/download/progress.js

@@ -1,2 +0,0 @@
-// Shim: re-exports from src/download/ for adapter imports
-export * from '../src/download/progress.js';

package/dist/pipeline/index.d.ts

@@ -1 +0,0 @@
-export * from '../src/pipeline/index.js';

package/dist/pipeline/index.js

@@ -1,2 +0,0 @@
-// Shim: re-exports from src/pipeline/ for adapter imports
-export * from '../src/pipeline/index.js';