@jackwener/opencli 1.4.1 → 1.5.1

package/dist/plugin-manifest.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Plugin manifest: reads and validates opencli-plugin.json files.
+ *
+ * Supports two modes:
+ * 1. Single plugin: repo root IS the plugin directory.
+ * 2. Monorepo: repo contains multiple plugins declared in `plugins` field.
+ */
+export interface SubPluginEntry {
+    /** Relative path from repo root to the sub-plugin directory. */
+    path: string;
+    version?: string;
+    description?: string;
+    /** Semver range for opencli compatibility (overrides top-level). */
+    opencli?: string;
+    /** When true, this sub-plugin is skipped during install. */
+    disabled?: boolean;
+}
+export interface PluginManifest {
+    /** Plugin name (single-plugin mode). */
+    name?: string;
+    /** Semantic version of the plugin (single-plugin mode). */
+    version?: string;
+    /** Semver range for opencli compatibility, e.g. ">=1.0.0". */
+    opencli?: string;
+    /** Human-readable description. */
+    description?: string;
+    /** Monorepo sub-plugins. Key = logical plugin name. */
+    plugins?: Record<string, SubPluginEntry>;
+}
+export declare const MANIFEST_FILENAME = "opencli-plugin.json";
+/**
+ * Read and parse opencli-plugin.json from a directory.
+ * Returns null if the file does not exist or is unparseable.
+ */
+export declare function readPluginManifest(dir: string): PluginManifest | null;
+/** Returns true when the manifest declares a monorepo (has `plugins` field). */
+export declare function isMonorepo(manifest: PluginManifest): boolean;
+/**
+ * Get the list of enabled sub-plugins from a monorepo manifest.
+ * Returns entries sorted by key name.
+ */
+export declare function getEnabledPlugins(manifest: PluginManifest): Array<{
+    name: string;
+    entry: SubPluginEntry;
+}>;
+/**
+ * Check if the current opencli version satisfies a semver range string.
+ *
+ * Supports a simplified subset of semver ranges:
+ *   ">=1.0.0"   – greater than or equal
+ *   "<=1.5.0"   – less than or equal
+ *   ">1.0.0"    – strictly greater
+ *   "<2.0.0"    – strictly less
+ *   "^1.2.0"    – compatible (>=1.2.0 and <2.0.0)
+ *   "~1.2.0"    – patch-level (>=1.2.0 and <1.3.0)
+ *   "1.2.0"     – exact match
+ *   ">=1.0.0 <2.0.0" – multiple constraints (space-separated, all must match)
+ *
+ * Returns true if compatible, false if not, and true for empty/undefined
+ * ranges (no constraint = always compatible).
+ */
+export declare function checkCompatibility(range: string | undefined): boolean;
+/** Parse a version string ("1.2.3") into [major, minor, patch]. */
+export declare function parseVersion(version: string): [number, number, number] | null;
+/**
+ * Check if a version string satisfies a range expression.
+ * Space-separated constraints are ANDed together.
+ */
+export declare function satisfiesRange(versionStr: string, range: string): boolean;
+export { readPluginManifest as _readPluginManifest, isMonorepo as _isMonorepo, getEnabledPlugins as _getEnabledPlugins, checkCompatibility as _checkCompatibility, parseVersion as _parseVersion, satisfiesRange as _satisfiesRange, };

package/dist/plugin-manifest.js

@@ -0,0 +1,160 @@
+/**
+ * Plugin manifest: reads and validates opencli-plugin.json files.
+ *
+ * Supports two modes:
+ * 1. Single plugin: repo root IS the plugin directory.
+ * 2. Monorepo: repo contains multiple plugins declared in `plugins` field.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { PKG_VERSION } from './version.js';
+export const MANIFEST_FILENAME = 'opencli-plugin.json';
+// ── Read / Validate ─────────────────────────────────────────────────────────
+/**
+ * Read and parse opencli-plugin.json from a directory.
+ * Returns null if the file does not exist or is unparseable.
+ */
+export function readPluginManifest(dir) {
+    const manifestPath = path.join(dir, MANIFEST_FILENAME);
+    try {
+        const raw = fs.readFileSync(manifestPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/** Returns true when the manifest declares a monorepo (has `plugins` field). */
+export function isMonorepo(manifest) {
+    return (manifest.plugins !== undefined &&
+        manifest.plugins !== null &&
+        typeof manifest.plugins === 'object' &&
+        Object.keys(manifest.plugins).length > 0);
+}
+/**
+ * Get the list of enabled sub-plugins from a monorepo manifest.
+ * Returns entries sorted by key name.
+ */
+export function getEnabledPlugins(manifest) {
+    if (!manifest.plugins)
+        return [];
+    return Object.entries(manifest.plugins)
+        .filter(([, entry]) => !entry.disabled)
+        .map(([name, entry]) => ({ name, entry }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+// ── Version compatibility ───────────────────────────────────────────────────
+/**
+ * Check if the current opencli version satisfies a semver range string.
+ *
+ * Supports a simplified subset of semver ranges:
+ *   ">=1.0.0"   – greater than or equal
+ *   "<=1.5.0"   – less than or equal
+ *   ">1.0.0"    – strictly greater
+ *   "<2.0.0"    – strictly less
+ *   "^1.2.0"    – compatible (>=1.2.0 and <2.0.0)
+ *   "~1.2.0"    – patch-level (>=1.2.0 and <1.3.0)
+ *   "1.2.0"     – exact match
+ *   ">=1.0.0 <2.0.0" – multiple constraints (space-separated, all must match)
+ *
+ * Returns true if compatible, false if not, and true for empty/undefined
+ * ranges (no constraint = always compatible).
+ */
+export function checkCompatibility(range) {
+    if (!range || range.trim() === '')
+        return true;
+    return satisfiesRange(PKG_VERSION, range);
+}
+/** Parse a version string ("1.2.3") into [major, minor, patch]. */
+export function parseVersion(version) {
+    const match = version.trim().match(/^(\d+)\.(\d+)\.(\d+)/);
+    if (!match)
+        return null;
+    return [parseInt(match[1], 10), parseInt(match[2], 10), parseInt(match[3], 10)];
+}
+/** Compare two version tuples: -1 if a<b, 0 if equal, 1 if a>b. */
+function compareVersions(a, b) {
+    for (let i = 0; i < 3; i++) {
+        if (a[i] < b[i])
+            return -1;
+        if (a[i] > b[i])
+            return 1;
+    }
+    return 0;
+}
+/** Check if a version satisfies a single constraint like ">=1.2.0". */
+function satisfiesSingleConstraint(version, constraint) {
+    const trimmed = constraint.trim();
+    if (!trimmed)
+        return true;
+    // ^1.2.0 → >=1.2.0 <2.0.0
+    if (trimmed.startsWith('^')) {
+        const target = parseVersion(trimmed.slice(1));
+        if (!target)
+            return true;
+        const upper = [target[0] + 1, 0, 0];
+        return compareVersions(version, target) >= 0 && compareVersions(version, upper) < 0;
+    }
+    // ~1.2.0 → >=1.2.0 <1.3.0
+    if (trimmed.startsWith('~')) {
+        const target = parseVersion(trimmed.slice(1));
+        if (!target)
+            return true;
+        const upper = [target[0], target[1] + 1, 0];
+        return compareVersions(version, target) >= 0 && compareVersions(version, upper) < 0;
+    }
+    // >=, <=, >, <, =
+    if (trimmed.startsWith('>=')) {
+        const target = parseVersion(trimmed.slice(2));
+        if (!target)
+            return true;
+        return compareVersions(version, target) >= 0;
+    }
+    if (trimmed.startsWith('<=')) {
+        const target = parseVersion(trimmed.slice(2));
+        if (!target)
+            return true;
+        return compareVersions(version, target) <= 0;
+    }
+    if (trimmed.startsWith('>')) {
+        const target = parseVersion(trimmed.slice(1));
+        if (!target)
+            return true;
+        return compareVersions(version, target) > 0;
+    }
+    if (trimmed.startsWith('<')) {
+        const target = parseVersion(trimmed.slice(1));
+        if (!target)
+            return true;
+        return compareVersions(version, target) < 0;
+    }
+    if (trimmed.startsWith('=')) {
+        const target = parseVersion(trimmed.slice(1));
+        if (!target)
+            return true;
+        return compareVersions(version, target) === 0;
+    }
+    // Exact match
+    const target = parseVersion(trimmed);
+    if (!target)
+        return true;
+    return compareVersions(version, target) === 0;
+}
+/**
+ * Check if a version string satisfies a range expression.
+ * Space-separated constraints are ANDed together.
+ */
+export function satisfiesRange(versionStr, range) {
+    const version = parseVersion(versionStr);
+    if (!version)
+        return true; // Can't parse our own version → assume ok
+    // Split on whitespace for multi-constraint ranges (e.g. ">=1.0.0 <2.0.0")
+    const constraints = range.trim().split(/\s+/);
+    return constraints.every((c) => satisfiesSingleConstraint(version, c));
+}
+// ── Exports for testing ─────────────────────────────────────────────────────
+export { readPluginManifest as _readPluginManifest, isMonorepo as _isMonorepo, getEnabledPlugins as _getEnabledPlugins, checkCompatibility as _checkCompatibility, parseVersion as _parseVersion, satisfiesRange as _satisfiesRange, };

package/dist/plugin-manifest.test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Tests for plugin manifest: reading, validating, and compatibility checks.
+ */
+export {};

package/dist/plugin-manifest.test.js

@@ -0,0 +1,179 @@
+/**
+ * Tests for plugin manifest: reading, validating, and compatibility checks.
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { _readPluginManifest as readPluginManifest, _isMonorepo as isMonorepo, _getEnabledPlugins as getEnabledPlugins, _parseVersion as parseVersion, _satisfiesRange as satisfiesRange, MANIFEST_FILENAME, } from './plugin-manifest.js';
+// ── readPluginManifest ──────────────────────────────────────────────────────
+describe('readPluginManifest', () => {
+    let tmpDir;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-manifest-test-'));
+    });
+    afterEach(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+    it('returns null when no manifest file exists', () => {
+        expect(readPluginManifest(tmpDir)).toBeNull();
+    });
+    it('returns null for malformed JSON', () => {
+        fs.writeFileSync(path.join(tmpDir, MANIFEST_FILENAME), 'not json {{{');
+        expect(readPluginManifest(tmpDir)).toBeNull();
+    });
+    it('returns null for non-object JSON (array)', () => {
+        fs.writeFileSync(path.join(tmpDir, MANIFEST_FILENAME), '["a","b"]');
+        expect(readPluginManifest(tmpDir)).toBeNull();
+    });
+    it('returns null for non-object JSON (string)', () => {
+        fs.writeFileSync(path.join(tmpDir, MANIFEST_FILENAME), '"hello"');
+        expect(readPluginManifest(tmpDir)).toBeNull();
+    });
+    it('reads a single-plugin manifest', () => {
+        const manifest = {
+            name: 'polymarket',
+            version: '1.2.0',
+            opencli: '>=1.0.0',
+            description: 'Prediction market analysis',
+        };
+        fs.writeFileSync(path.join(tmpDir, MANIFEST_FILENAME), JSON.stringify(manifest));
+        const result = readPluginManifest(tmpDir);
+        expect(result).toEqual(manifest);
+    });
+    it('reads a monorepo manifest', () => {
+        const manifest = {
+            version: '1.0.0',
+            opencli: '>=0.9.0',
+            description: 'My plugin collection',
+            plugins: {
+                polymarket: {
+                    path: 'packages/polymarket',
+                    description: 'Prediction market',
+                    version: '1.2.0',
+                },
+                defi: {
+                    path: 'packages/defi',
+                    description: 'DeFi data',
+                    version: '0.8.0',
+                    disabled: true,
+                },
+            },
+        };
+        fs.writeFileSync(path.join(tmpDir, MANIFEST_FILENAME), JSON.stringify(manifest));
+        const result = readPluginManifest(tmpDir);
+        expect(result).toEqual(manifest);
+        expect(result.plugins.polymarket.path).toBe('packages/polymarket');
+        expect(result.plugins.defi.disabled).toBe(true);
+    });
+});
+// ── isMonorepo ──────────────────────────────────────────────────────────────
+describe('isMonorepo', () => {
+    it('returns false for single-plugin manifest', () => {
+        expect(isMonorepo({ name: 'test', version: '1.0.0' })).toBe(false);
+    });
+    it('returns false for empty plugins object', () => {
+        expect(isMonorepo({ plugins: {} })).toBe(false);
+    });
+    it('returns true for manifest with plugins', () => {
+        expect(isMonorepo({
+            plugins: {
+                foo: { path: 'packages/foo' },
+            },
+        })).toBe(true);
+    });
+});
+// ── getEnabledPlugins ───────────────────────────────────────────────────────
+describe('getEnabledPlugins', () => {
+    it('returns empty array for no plugins', () => {
+        expect(getEnabledPlugins({ name: 'test' })).toEqual([]);
+    });
+    it('filters out disabled plugins', () => {
+        const manifest = {
+            plugins: {
+                foo: { path: 'packages/foo' },
+                bar: { path: 'packages/bar', disabled: true },
+                baz: { path: 'packages/baz' },
+            },
+        };
+        const result = getEnabledPlugins(manifest);
+        expect(result).toHaveLength(2);
+        expect(result.map((r) => r.name)).toEqual(['baz', 'foo']); // sorted
+    });
+    it('returns all when none disabled', () => {
+        const manifest = {
+            plugins: {
+                charlie: { path: 'packages/charlie' },
+                alpha: { path: 'packages/alpha' },
+            },
+        };
+        const result = getEnabledPlugins(manifest);
+        expect(result).toHaveLength(2);
+        expect(result[0].name).toBe('alpha');
+        expect(result[1].name).toBe('charlie');
+    });
+});
+// ── parseVersion ────────────────────────────────────────────────────────────
+describe('parseVersion', () => {
+    it('parses standard versions', () => {
+        expect(parseVersion('1.2.3')).toEqual([1, 2, 3]);
+        expect(parseVersion('0.0.0')).toEqual([0, 0, 0]);
+        expect(parseVersion('10.20.30')).toEqual([10, 20, 30]);
+    });
+    it('parses versions with prerelease suffix', () => {
+        expect(parseVersion('1.2.3-beta.1')).toEqual([1, 2, 3]);
+    });
+    it('returns null for invalid versions', () => {
+        expect(parseVersion('abc')).toBeNull();
+        expect(parseVersion('')).toBeNull();
+        expect(parseVersion('1.2')).toBeNull();
+    });
+});
+// ── satisfiesRange ──────────────────────────────────────────────────────────
+describe('satisfiesRange', () => {
+    it('handles >= constraint', () => {
+        expect(satisfiesRange('1.4.1', '>=1.0.0')).toBe(true);
+        expect(satisfiesRange('1.0.0', '>=1.0.0')).toBe(true);
+        expect(satisfiesRange('0.9.9', '>=1.0.0')).toBe(false);
+    });
+    it('handles <= constraint', () => {
+        expect(satisfiesRange('1.0.0', '<=1.0.0')).toBe(true);
+        expect(satisfiesRange('0.9.0', '<=1.0.0')).toBe(true);
+        expect(satisfiesRange('1.0.1', '<=1.0.0')).toBe(false);
+    });
+    it('handles > constraint', () => {
+        expect(satisfiesRange('1.0.1', '>1.0.0')).toBe(true);
+        expect(satisfiesRange('1.0.0', '>1.0.0')).toBe(false);
+    });
+    it('handles < constraint', () => {
+        expect(satisfiesRange('0.9.9', '<1.0.0')).toBe(true);
+        expect(satisfiesRange('1.0.0', '<1.0.0')).toBe(false);
+    });
+    it('handles ^ (caret) constraint', () => {
+        expect(satisfiesRange('1.2.0', '^1.2.0')).toBe(true);
+        expect(satisfiesRange('1.9.9', '^1.2.0')).toBe(true);
+        expect(satisfiesRange('2.0.0', '^1.2.0')).toBe(false);
+        expect(satisfiesRange('1.1.0', '^1.2.0')).toBe(false);
+    });
+    it('handles ~ (tilde) constraint', () => {
+        expect(satisfiesRange('1.2.0', '~1.2.0')).toBe(true);
+        expect(satisfiesRange('1.2.9', '~1.2.0')).toBe(true);
+        expect(satisfiesRange('1.3.0', '~1.2.0')).toBe(false);
+    });
+    it('handles exact match', () => {
+        expect(satisfiesRange('1.2.3', '1.2.3')).toBe(true);
+        expect(satisfiesRange('1.2.4', '1.2.3')).toBe(false);
+    });
+    it('handles compound range (AND)', () => {
+        expect(satisfiesRange('1.5.0', '>=1.0.0 <2.0.0')).toBe(true);
+        expect(satisfiesRange('2.0.0', '>=1.0.0 <2.0.0')).toBe(false);
+        expect(satisfiesRange('0.9.0', '>=1.0.0 <2.0.0')).toBe(false);
+    });
+    it('returns true for empty range', () => {
+        expect(satisfiesRange('1.0.0', '')).toBe(true);
+        expect(satisfiesRange('1.0.0', '  ')).toBe(true);
+    });
+    it('returns true for unparseable version', () => {
+        expect(satisfiesRange('dev', '>=1.0.0')).toBe(true);
+    });
+});

package/dist/plugin-scaffold.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Plugin scaffold: generates a ready-to-develop plugin directory.
+ *
+ * Usage: opencli plugin create <name> [--dir <path>]
+ *
+ * Creates:
+ *   <name>/
+ *     opencli-plugin.json   — manifest with name, version, description
+ *     package.json          — ESM package with opencli peer dependency
+ *     hello.yaml            — sample YAML command
+   *     greet.ts              — sample TS command using the current registry API
+ *     README.md             — basic documentation
+ */
+export interface ScaffoldOptions {
+    /** Directory to create the plugin in. Defaults to `./<name>` */
+    dir?: string;
+    /** Plugin description */
+    description?: string;
+}
+export interface ScaffoldResult {
+    name: string;
+    dir: string;
+    files: string[];
+}
+/**
+ * Create a new plugin scaffold directory.
+ */
+export declare function createPluginScaffold(name: string, opts?: ScaffoldOptions): ScaffoldResult;

package/dist/plugin-scaffold.js

@@ -0,0 +1,142 @@
+/**
+ * Plugin scaffold: generates a ready-to-develop plugin directory.
+ *
+ * Usage: opencli plugin create <name> [--dir <path>]
+ *
+ * Creates:
+ *   <name>/
+ *     opencli-plugin.json   — manifest with name, version, description
+ *     package.json          — ESM package with opencli peer dependency
+ *     hello.yaml            — sample YAML command
+   *     greet.ts              — sample TS command using the current registry API
+ *     README.md             — basic documentation
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { PKG_VERSION } from './version.js';
+/**
+ * Create a new plugin scaffold directory.
+ */
+export function createPluginScaffold(name, opts = {}) {
+    // Validate name
+    if (!/^[a-z][a-z0-9-]*$/.test(name)) {
+        throw new Error(`Invalid plugin name "${name}". ` +
+            `Plugin names must start with a lowercase letter and contain only lowercase letters, digits, and hyphens.`);
+    }
+    const targetDir = opts.dir
+        ? path.resolve(opts.dir)
+        : path.resolve(name);
+    if (fs.existsSync(targetDir) && fs.readdirSync(targetDir).length > 0) {
+        throw new Error(`Directory "${targetDir}" already exists and is not empty.`);
+    }
+    fs.mkdirSync(targetDir, { recursive: true });
+    const files = [];
+    // opencli-plugin.json
+    const manifest = {
+        name,
+        version: '0.1.0',
+        description: opts.description ?? `An opencli plugin: ${name}`,
+        opencli: `>=${PKG_VERSION}`,
+    };
+    writeFile(targetDir, 'opencli-plugin.json', JSON.stringify(manifest, null, 2) + '\n');
+    files.push('opencli-plugin.json');
+    // package.json
+    const pkg = {
+        name: `opencli-plugin-${name}`,
+        version: '0.1.0',
+        type: 'module',
+        description: opts.description ?? `An opencli plugin: ${name}`,
+        peerDependencies: {
+            '@jackwener/opencli': `>=${PKG_VERSION}`,
+        },
+    };
+    writeFile(targetDir, 'package.json', JSON.stringify(pkg, null, 2) + '\n');
+    files.push('package.json');
+    // hello.yaml — sample YAML command
+    const yamlContent = `# Sample YAML command for ${name}
+# See: https://github.com/jackwener/opencli#yaml-commands
+
+site: ${name}
+name: hello
+description: "A sample YAML command"
+strategy: public
+browser: false
+
+domain: https://httpbin.org
+
+pipeline:
+  - fetch:
+      url: "https://httpbin.org/get?greeting=hello"
+      method: GET
+  - extract:
+      type: json
+      selector: "$.args"
+`;
+    writeFile(targetDir, 'hello.yaml', yamlContent);
+    files.push('hello.yaml');
+    // greet.ts — sample TS command using registry API
+    const tsContent = `/**
+ * Sample TypeScript command for ${name}.
+ * Demonstrates the programmatic cli() registration API.
+ */
+
+import { cli, Strategy } from '@jackwener/opencli/registry';
+
+cli({
+  site: '${name}',
+  name: 'greet',
+  description: 'Greet someone by name',
+  strategy: Strategy.PUBLIC,
+  browser: false,
+  args: [
+    { name: 'name', positional: true, required: true, help: 'Name to greet' },
+  ],
+  columns: ['greeting'],
+  func: async (_page, kwargs) => [{ greeting: \`Hello, \${String(kwargs.name ?? 'World')}!\` }],
+});
+`;
+    writeFile(targetDir, 'greet.ts', tsContent);
+    files.push('greet.ts');
+    // README.md
+    const readme = `# opencli-plugin-${name}
+
+${opts.description ?? `An opencli plugin: ${name}`}
+
+## Install
+
+\`\`\`bash
+# From local development directory
+opencli plugin install file://${targetDir}
+
+# From GitHub (after publishing)
+opencli plugin install github:<user>/opencli-plugin-${name}
+\`\`\`
+
+## Commands
+
+| Command | Type | Description |
+|---------|------|-------------|
+| \`${name}/hello\` | YAML | Sample YAML command |
+| \`${name}/greet\` | TypeScript | Sample TS command |
+
+## Development
+
+\`\`\`bash
+# Install locally for development (symlinked, changes reflect immediately)
+opencli plugin install file://${targetDir}
+
+# Verify commands are registered
+opencli list | grep ${name}
+
+# Run a command
+opencli ${name} hello
+opencli ${name} greet --name World
+\`\`\`
+`;
+    writeFile(targetDir, 'README.md', readme);
+    files.push('README.md');
+    return { name, dir: targetDir, files };
+}
+function writeFile(dir, name, content) {
+    fs.writeFileSync(path.join(dir, name), content);
+}

package/dist/plugin-scaffold.test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Tests for plugin scaffold: create new plugin directories.
+ */
+export {};

package/dist/plugin-scaffold.test.js

@@ -0,0 +1,83 @@
+/**
+ * Tests for plugin scaffold: create new plugin directories.
+ */
+import { describe, it, expect, afterEach } from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { createPluginScaffold } from './plugin-scaffold.js';
+describe('createPluginScaffold', () => {
+    const createdDirs = [];
+    afterEach(() => {
+        for (const dir of createdDirs) {
+            try {
+                fs.rmSync(dir, { recursive: true, force: true });
+            }
+            catch { }
+        }
+        createdDirs.length = 0;
+    });
+    it('creates all expected files', () => {
+        const dir = path.join(os.tmpdir(), `opencli-scaffold-${Date.now()}`);
+        createdDirs.push(dir);
+        const result = createPluginScaffold('my-test', { dir });
+        expect(result.name).toBe('my-test');
+        expect(result.dir).toBe(dir);
+        expect(result.files).toContain('opencli-plugin.json');
+        expect(result.files).toContain('package.json');
+        expect(result.files).toContain('hello.yaml');
+        expect(result.files).toContain('greet.ts');
+        expect(result.files).toContain('README.md');
+        // All files exist
+        for (const f of result.files) {
+            expect(fs.existsSync(path.join(dir, f))).toBe(true);
+        }
+    });
+    it('generates valid opencli-plugin.json', () => {
+        const dir = path.join(os.tmpdir(), `opencli-scaffold-${Date.now()}`);
+        createdDirs.push(dir);
+        createPluginScaffold('test-manifest', { dir, description: 'Test desc' });
+        const manifest = JSON.parse(fs.readFileSync(path.join(dir, 'opencli-plugin.json'), 'utf-8'));
+        expect(manifest.name).toBe('test-manifest');
+        expect(manifest.version).toBe('0.1.0');
+        expect(manifest.description).toBe('Test desc');
+        expect(manifest.opencli).toMatch(/^>=/);
+    });
+    it('generates ESM package.json', () => {
+        const dir = path.join(os.tmpdir(), `opencli-scaffold-${Date.now()}`);
+        createdDirs.push(dir);
+        createPluginScaffold('test-pkg', { dir });
+        const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf-8'));
+        expect(pkg.type).toBe('module');
+        expect(pkg.peerDependencies?.['@jackwener/opencli']).toBeDefined();
+    });
+    it('generates a TS sample that matches the current plugin API', () => {
+        const dir = path.join(os.tmpdir(), `opencli-scaffold-${Date.now()}`);
+        createdDirs.push(dir);
+        createPluginScaffold('test-ts', { dir });
+        const tsSample = fs.readFileSync(path.join(dir, 'greet.ts'), 'utf-8');
+        expect(tsSample).toContain(`import { cli, Strategy } from '@jackwener/opencli/registry';`);
+        expect(tsSample).toContain(`strategy: Strategy.PUBLIC`);
+        expect(tsSample).toContain(`help: 'Name to greet'`);
+        expect(tsSample).toContain(`func: async (_page, kwargs)`);
+        expect(tsSample).not.toContain('async run(');
+    });
+    it('documents a supported local install flow', () => {
+        const dir = path.join(os.tmpdir(), `opencli-scaffold-${Date.now()}`);
+        createdDirs.push(dir);
+        createPluginScaffold('test-readme', { dir });
+        const readme = fs.readFileSync(path.join(dir, 'README.md'), 'utf-8');
+        expect(readme).toContain(`opencli plugin install file://${dir}`);
+    });
+    it('rejects invalid names', () => {
+        expect(() => createPluginScaffold('Bad_Name')).toThrow('Invalid plugin name');
+        expect(() => createPluginScaffold('123start')).toThrow('Invalid plugin name');
+    });
+    it('rejects non-empty directory', () => {
+        const dir = path.join(os.tmpdir(), `opencli-scaffold-${Date.now()}`);
+        createdDirs.push(dir);
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(path.join(dir, 'existing.txt'), 'x');
+        expect(() => createPluginScaffold('test', { dir })).toThrow('not empty');
+    });
+});