@jackwener/opencli 1.5.0 → 1.5.1

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');
+    });
+});

package/dist/plugin.d.ts

@@ -3,26 +3,31 @@
  *
  * Plugins live in ~/.opencli/plugins/<name>/.
  * Monorepo clones live in ~/.opencli/monorepos/<repo-name>/.
- * Install source format: "github:user/repo" or "github:user/repo/subplugin"
+ * Install source format: "github:user/repo", "github:user/repo/subplugin",
+ * "https://github.com/user/repo", "file:///local/plugin", or a local directory path.
  */
+import * as fs from 'node:fs';
 /** Path to the lock file that tracks installed plugin versions. */
 export declare function getLockFilePath(): string;
 /** Monorepo clones directory: ~/.opencli/monorepos/ */
 export declare function getMonoreposDir(): string;
-export declare const LOCK_FILE: string;
-export declare const MONOREPOS_DIR: string;
+export type PluginSourceRecord = {
+    kind: 'git';
+    url: string;
+} | {
+    kind: 'local';
+    path: string;
+} | {
+    kind: 'monorepo';
+    url: string;
+    repoName: string;
+    subPath: string;
+};
 export interface LockEntry {
-    source: string;
+    source: PluginSourceRecord;
     commitHash: string;
     installedAt: string;
     updatedAt?: string;
-    /** Present when this plugin comes from a monorepo. */
-    monorepo?: {
-        /** Monorepo directory name under ~/.opencli/monorepos/ */
-        name: string;
-        /** Relative path of this sub-plugin within the monorepo. */
-        subPath: string;
-    };
 }
 export interface PluginInfo {
     name: string;
@@ -36,11 +41,40 @@ export interface PluginInfo {
     /** Description from opencli-plugin.json. */
     description?: string;
 }
+interface ParsedSource {
+    type: 'git' | 'local';
+    name: string;
+    subPlugin?: string;
+    cloneUrl?: string;
+    localPath?: string;
+}
+declare function isLocalPluginSource(source?: string): boolean;
+declare function toStoredPluginSource(source: PluginSourceRecord): string;
+declare function toLocalPluginSource(pluginDir: string): string;
+declare function resolvePluginSource(lockEntry: LockEntry | undefined, pluginDir: string): PluginSourceRecord | undefined;
+declare function resolveStoredPluginSource(lockEntry: LockEntry | undefined, pluginDir: string): string | undefined;
+/**
+ * Move a directory, with EXDEV fallback.
+ * fs.renameSync fails when source and destination are on different
+ * filesystems (e.g. /tmp → ~/.opencli). In that case we copy then remove.
+ */
+type MoveDirFsOps = Pick<typeof fs, 'renameSync' | 'cpSync' | 'rmSync'>;
+declare function moveDir(src: string, dest: string, fsOps?: MoveDirFsOps): void;
+type PromoteDirFsOps = MoveDirFsOps & Pick<typeof fs, 'existsSync' | 'mkdirSync'>;
+/**
+ * Promote a prepared staging directory into its final location.
+ * The final path is only exposed after the directory has been fully prepared.
+ */
+declare function promoteDir(stagingDir: string, dest: string, fsOps?: PromoteDirFsOps): void;
+declare function replaceDir(stagingDir: string, dest: string, fsOps?: PromoteDirFsOps): void;
 export interface ValidationResult {
     valid: boolean;
     errors: string[];
 }
+declare function readLockFileWithWriter(writeLock?: (lock: Record<string, LockEntry>) => void): Record<string, LockEntry>;
 export declare function readLockFile(): Record<string, LockEntry>;
+type WriteLockFileFsOps = Pick<typeof fs, 'mkdirSync' | 'writeFileSync' | 'renameSync' | 'rmSync'>;
+declare function writeLockFileWithFs(lock: Record<string, LockEntry>, fsOps?: WriteLockFileFsOps): void;
 export declare function writeLockFile(lock: Record<string, LockEntry>): void;
 /** Get the HEAD commit hash of a git repo directory. */
 export declare function getCommitHash(dir: string): string | undefined;
@@ -61,10 +95,18 @@ declare function postInstallMonorepoLifecycle(repoDir: string, pluginDirs: strin
  *   "github:user/repo"            — single plugin or full monorepo
  *   "github:user/repo/subplugin"  — specific sub-plugin from a monorepo
  *   "https://github.com/user/repo"
+ *   "file:///absolute/path"       — local plugin directory (symlinked)
+ *   "/absolute/path"              — local plugin directory (symlinked)
  *
  * Returns the installed plugin name(s).
  */
 export declare function installPlugin(source: string): string | string[];
+/**
+ * Install a local plugin by creating a symlink.
+ * Used for plugin development: the source directory is symlinked into
+ * the plugins dir so changes are reflected immediately.
+ */
+declare function installLocalPlugin(localPath: string, name: string): string;
 /**
  * Uninstall a plugin by name.
  * For monorepo sub-plugins: removes symlink and cleans up the monorepo
@@ -95,13 +137,9 @@ export declare function updateAllPlugins(): UpdateResult[];
  */
 export declare function listPlugins(): PluginInfo[];
 /** Parse a plugin source string into clone URL, repo name, and optional sub-plugin. */
-declare function parseSource(source: string): {
-    cloneUrl: string;
-    name: string;
-    subPlugin?: string;
-} | null;
+declare function parseSource(source: string): ParsedSource | null;
 /**
  * Resolve the path to the esbuild CLI executable with fallback strategies.
  */
 export declare function resolveEsbuildBin(): string | null;
-export { resolveEsbuildBin as _resolveEsbuildBin, getCommitHash as _getCommitHash, installDependencies as _installDependencies, parseSource as _parseSource, postInstallMonorepoLifecycle as _postInstallMonorepoLifecycle, readLockFile as _readLockFile, updateAllPlugins as _updateAllPlugins, validatePluginStructure as _validatePluginStructure, writeLockFile as _writeLockFile, isSymlinkSync as _isSymlinkSync, getMonoreposDir as _getMonoreposDir, };
+export { resolveEsbuildBin as _resolveEsbuildBin, getCommitHash as _getCommitHash, installDependencies as _installDependencies, parseSource as _parseSource, postInstallMonorepoLifecycle as _postInstallMonorepoLifecycle, readLockFile as _readLockFile, readLockFileWithWriter as _readLockFileWithWriter, updateAllPlugins as _updateAllPlugins, validatePluginStructure as _validatePluginStructure, writeLockFile as _writeLockFile, writeLockFileWithFs as _writeLockFileWithFs, isSymlinkSync as _isSymlinkSync, getMonoreposDir as _getMonoreposDir, installLocalPlugin as _installLocalPlugin, isLocalPluginSource as _isLocalPluginSource, moveDir as _moveDir, promoteDir as _promoteDir, replaceDir as _replaceDir, resolvePluginSource as _resolvePluginSource, resolveStoredPluginSource as _resolveStoredPluginSource, toStoredPluginSource as _toStoredPluginSource, toLocalPluginSource as _toLocalPluginSource, };