@jackwener/opencli 1.4.1 → 1.5.1

package/src/plugin-manifest.test.ts

@@ -0,0 +1,223 @@
+/**
+ * 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,
+  type PluginManifest,
+} from './plugin-manifest.js';
+
+// ── readPluginManifest ──────────────────────────────────────────────────────
+
+describe('readPluginManifest', () => {
+  let tmpDir: string;
+
+  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: PluginManifest = {
+      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: PluginManifest = {
+      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: PluginManifest = {
+      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: PluginManifest = {
+      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/src/plugin-manifest.ts

@@ -0,0 +1,206 @@
+/**
+ * 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';
+
+// ── Types ───────────────────────────────────────────────────────────────────
+
+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 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: string): PluginManifest | null {
+  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 as PluginManifest;
+  } catch {
+    return null;
+  }
+}
+
+/** Returns true when the manifest declares a monorepo (has `plugins` field). */
+export function isMonorepo(manifest: PluginManifest): boolean {
+  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: PluginManifest,
+): Array<{ name: string; entry: SubPluginEntry }> {
+  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: string | undefined): boolean {
+  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: string): [number, number, number] | null {
+  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: [number, number, number],
+  b: [number, number, number],
+): -1 | 0 | 1 {
+  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: [number, number, number],
+  constraint: string,
+): boolean {
+  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: [number, number, number] = [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: [number, number, number] = [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: string, range: string): boolean {
+  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/src/plugin-scaffold.test.ts

@@ -0,0 +1,98 @@
+/**
+ * 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: string[] = [];
+
+  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');
+  });
+});

package/src/plugin-scaffold.ts

@@ -0,0 +1,170 @@
+/**
+ * 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';
+
+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 function createPluginScaffold(name: string, opts: ScaffoldOptions = {}): ScaffoldResult {
+  // 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: string[] = [];
+
+  // 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: string, name: string, content: string): void {
+  fs.writeFileSync(path.join(dir, name), content);
+}