@jackwener/opencli 1.5.0 → 1.5.2

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, };