publishport-opencli 1.0.0

package/dist/src/plugin-scaffold.js

@@ -0,0 +1,75 @@
+import*as H from"node:fs";import*as J from"node:path";import{PKG_VERSION as L}from"./version.js";export function createPluginScaffold(b,x={}){if(!/^[a-z][a-z0-9-]*$/.test(b))throw Error(`Invalid plugin name "${b}". Plugin names must start with a lowercase letter and contain only lowercase letters, digits, and hyphens.`);const q=x.dir?J.resolve(x.dir):J.resolve(b);if(H.existsSync(q)&&H.readdirSync(q).length>0)throw Error(`Directory "${q}" already exists and is not empty.`);H.mkdirSync(q,{recursive:!0});const z=[],Q={name:b,version:"0.1.0",description:x.description??`An opencli plugin: ${b}`,opencli:`>=${L}`};B(q,"opencli-plugin.json",JSON.stringify(Q,null,2)+`
+`);z.push("opencli-plugin.json");const U={name:`opencli-plugin-${b}`,version:"0.1.0",type:"module",description:x.description??`An opencli plugin: ${b}`,peerDependencies:{"@jackwener/opencli":`>=${L}`}};B(q,"package.json",JSON.stringify(U,null,2)+`
+`);z.push("package.json");const W=`/**
+ * Sample pipeline command for ${b}.
+ * Demonstrates the declarative pipeline API.
+ */
+
+import { cli, Strategy } from '@jackwener/opencli/registry';
+
+cli({
+  site: '${b}',
+  name: 'hello',
+  description: 'A sample pipeline command',
+  strategy: Strategy.PUBLIC,
+  browser: false,
+  columns: ['greeting'],
+  pipeline: [
+    { fetch: { url: 'https://httpbin.org/get?greeting=hello' } },
+    { select: 'args' },
+  ],
+});
+`;B(q,"hello.ts",W);z.push("hello.ts");const X=`/**
+ * Sample TypeScript command for ${b}.
+ * Demonstrates the programmatic cli() registration API.
+ */
+
+import { cli, Strategy } from '@jackwener/opencli/registry';
+
+cli({
+  site: '${b}',
+  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 (kwargs) => [{ greeting: \`Hello, \${String(kwargs.name ?? 'World')}!\` }],
+});
+`;B(q,"greet.ts",X);z.push("greet.ts");const Y=`# opencli-plugin-${b}
+
+${x.description??`An opencli plugin: ${b}`}
+
+## Install
+
+\`\`\`bash
+# From local development directory
+opencli plugin install file://${q}
+
+# From GitHub (after publishing)
+opencli plugin install github:<user>/opencli-plugin-${b}
+\`\`\`
+
+## Commands
+
+| Command | Type | Description |
+|---------|------|-------------|
+| \`${b}/hello\` | Pipeline | Sample pipeline command |
+| \`${b}/greet\` | TypeScript | Sample TS command with func() |
+
+## Development
+
+\`\`\`bash
+# Install locally for development (symlinked, changes reflect immediately)
+opencli plugin install file://${q}
+
+# Verify commands are registered
+opencli list | grep ${b}
+
+# Run a command
+opencli ${b} hello
+opencli ${b} greet --name World
+\`\`\`
+`;B(q,"README.md",Y);z.push("README.md");return{name:b,dir:q,files:z}}function B(b,x,q){H.writeFileSync(J.join(b,x),q)}

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

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

package/dist/src/plugin.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Plugin management: install, uninstall, and list plugins.
+ *
+ * Plugins live in ~/.opencli/plugins/<name>/.
+ * Monorepo clones live in ~/.opencli/monorepos/<repo-name>/.
+ * 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 type PluginSourceRecord = {
+    kind: 'git';
+    url: string;
+} | {
+    kind: 'local';
+    path: string;
+} | {
+    kind: 'monorepo';
+    url: string;
+    repoName: string;
+    subPath: string;
+};
+export interface LockEntry {
+    source: PluginSourceRecord;
+    commitHash: string;
+    installedAt: string;
+    updatedAt?: string;
+}
+export interface PluginInfo {
+    name: string;
+    path: string;
+    commands: string[];
+    source?: string;
+    version?: string;
+    installedAt?: string;
+    /** If from a monorepo, the monorepo name. */
+    monorepoName?: string;
+    /** 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;
+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;
+/**
+ * Validate that a downloaded plugin directory is a structurally valid plugin.
+ * Checks for at least one command file (.ts, .js) and a valid
+ * package.json if it contains .ts files.
+ */
+export declare function validatePluginStructure(pluginDir: string): ValidationResult;
+declare function installDependencies(dir: string): void;
+/**
+ * Monorepo lifecycle: install shared deps at repo root, then install and finalize each sub-plugin.
+ *
+ * The root install covers monorepos that use npm workspaces to hoist dependencies.
+ * For monorepos that do NOT use workspaces, sub-plugins may declare their own
+ * production dependencies in their package.json.  We install those per sub-plugin
+ * so that runtime imports (e.g. `undici`) can be resolved from the sub-plugin
+ * directory.  When the root already satisfies all deps this is a fast no-op.
+ */
+declare function postInstallMonorepoLifecycle(repoDir: string, pluginDirs: string[]): void;
+/**
+ * Install a plugin from a source.
+ * Supports:
+ *   "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
+ * directory when no more sub-plugins reference it.
+ */
+export declare function uninstallPlugin(name: string): void;
+/** Synchronous check if a path is a symlink. */
+declare function isSymlinkSync(p: string): boolean;
+/**
+ * Update a plugin by name (git pull + re-install lifecycle).
+ * For monorepo sub-plugins: pulls the monorepo root and re-runs lifecycle
+ * for all sub-plugins from the same monorepo.
+ */
+export declare function updatePlugin(name: string): void;
+export interface UpdateResult {
+    name: string;
+    success: boolean;
+    error?: string;
+}
+/**
+ * Update all installed plugins.
+ * Continues even if individual plugin updates fail.
+ */
+export declare function updateAllPlugins(): UpdateResult[];
+/**
+ * List all installed plugins.
+ * Reads opencli-plugin.json for description/version when available.
+ */
+export declare function listPlugins(): PluginInfo[];
+/** Parse a plugin source string into clone URL, repo name, and optional sub-plugin. */
+declare function parseSource(source: string): ParsedSource | null;
+/**
+ * Resolve the path to the esbuild CLI executable with fallback strategies.
+ */
+export declare function resolveEsbuildBin(): string | null;
+declare function resolveHostOpencliRoot(startFile?: string): string;
+export { resolveHostOpencliRoot as _resolveHostOpencliRoot, 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, resolvePluginSource as _resolvePluginSource, resolveStoredPluginSource as _resolveStoredPluginSource, toStoredPluginSource as _toStoredPluginSource, toLocalPluginSource as _toLocalPluginSource, };

package/dist/src/plugin.js

@@ -0,0 +1,20 @@
+import*as X from"node:fs";import*as u from"node:os";import*as B from"node:path";import{execSync as r,execFileSync as v}from"node:child_process";import{fileURLToPath as f}from"node:url";import{PLUGINS_DIR as x}from"./discovery.js";import{getErrorMessage as U,PluginError as G}from"./errors.js";import{log as T}from"./logger.js";import{isRecord as L}from"./utils.js";import{readPluginManifest as F,isMonorepo as b,getEnabledPlugins as i,checkCompatibility as O}from"./plugin-manifest.js";const I=process.platform==="win32",P="local:";function c(){return process.env.HOME||process.env.USERPROFILE||u.homedir()}export function getLockFilePath(){return B.join(c(),".opencli","plugins.lock.json")}export function getMonoreposDir(){return B.join(c(),".opencli","monorepos")}function k(q){if(!q)return;if(q.startsWith(P))return{kind:"local",path:B.resolve(q.slice(P.length))};return{kind:"git",url:q}}function isLocalPluginSource(q){return k(q)?.kind==="local"}function toStoredPluginSource(q){if(q.kind==="local")return`${P}${B.resolve(q.path)}`;return q.url}function toLocalPluginSource(q){return toStoredPluginSource({kind:"local",path:q})}function e(q){if(!L(q))return;if(typeof q.name!=="string"||typeof q.subPath!=="string")return;return{name:q.name,subPath:q.subPath}}function qq(q,K){if(typeof q==="string"){const Q=k(q);if(!Q)return;if(Q.kind==="git"&&K)return{kind:"monorepo",url:Q.url,repoName:K.name,subPath:K.subPath};return Q}if(!L(q)||typeof q.kind!=="string")return;switch(q.kind){case"git":return typeof q.url==="string"?{kind:"git",url:q.url}:void 0;case"local":return typeof q.path==="string"?{kind:"local",path:B.resolve(q.path)}:void 0;case"monorepo":return typeof q.url==="string"&&typeof q.repoName==="string"&&typeof q.subPath==="string"?{kind:"monorepo",url:q.url,repoName:q.repoName,subPath:q.subPath}:void 0;default:return}}function Kq(q){if(!L(q))return;const K=e(q.monorepo),Q=qq(q.source,K);if(!Q)return;if(typeof q.commitHash!=="string"||typeof q.installedAt!=="string")return;const V={source:Q,commitHash:q.commitHash,installedAt:q.installedAt};if(typeof q.updatedAt==="string")V.updatedAt=q.updatedAt;return V}function resolvePluginSource(q,K){if(q)return q.source;return k(Wq(K))}function resolveStoredPluginSource(q,K){const Q=resolvePluginSource(q,K);return Q?toStoredPluginSource(Q):void 0}function moveDir(q,K,Q=X){try{Q.renameSync(q,K)}catch(V){if(V.code==="EXDEV"){try{Q.cpSync(q,K,{recursive:!0})}catch(Y){try{Q.rmSync(K,{recursive:!0,force:!0})}catch{}throw Y}Q.rmSync(q,{recursive:!0,force:!0})}else throw V}}function S(q,K){const Q=`${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;return B.join(B.dirname(q),`.${B.basename(q)}.${K}-${Q}`)}function Qq(q){const K=B.join(u.tmpdir(),`opencli-clone-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`);try{v("git",["clone","--depth","1",q,K],{encoding:"utf-8",stdio:["pipe","pipe","pipe"]})}catch(Q){throw new G(`Failed to clone plugin: ${U(Q)}`,"Check the repository URL and your network connection.")}return K}function d(q,K){const Q=Qq(q);try{return K(Q)}finally{try{X.rmSync(Q,{recursive:!0,force:!0})}catch{}}}function Vq(q,K){const Q=resolvePluginSource(q,K);if(!Q||Q.kind==="local")throw Error(`Unable to determine remote source for plugin at ${K}`);return Q.url}function y(q){try{X.lstatSync(q);return!0}catch{return!1}}function C(q,K){const Q=B.resolve(q,K);if(!Q.startsWith(q+B.sep)&&Q!==q)throw new G(`Plugin path "${K}" escapes repo root.`);return Q}function D(q){try{if(X.lstatSync(q).isSymbolicLink()){X.unlinkSync(q);return}X.rmSync(q,{recursive:!0,force:!0})}catch{}}class t{#K=[];#q=!1;track(q){this.#K.push(q);return q}commit(){if(this.#q)return;this.#q=!0;for(const q of this.#K)q.finalize()}rollback(){if(this.#q)return;this.#q=!0;for(const q of[...this.#K].reverse())q.rollback()}}function p(q){const K=new t;try{const Q=q(K);K.commit();return Q}catch(Q){K.rollback();throw Q}}function a(q,K,Q=X){const V=Q.existsSync(K);Q.mkdirSync(B.dirname(K),{recursive:!0});const Y=S(K,"tmp"),Z=V?S(K,"bak"):null;let J=!1;try{moveDir(q,Y,Q);if(Z)Q.renameSync(K,Z);Q.renameSync(Y,K)}catch($){try{Q.rmSync(Y,{recursive:!0,force:!0})}catch{}if(Z&&!Q.existsSync(K))try{Q.renameSync(Z,K)}catch{}throw $}return{finalize(){if(J)return;J=!0;if(Z)try{Q.rmSync(Z,{recursive:!0,force:!0})}catch{}},rollback(){if(J)return;J=!0;try{Q.rmSync(K,{recursive:!0,force:!0})}catch{}if(Z)try{Q.renameSync(Z,K)}catch{}try{Q.rmSync(Y,{recursive:!0,force:!0})}catch{}}}}function Yq(q,K){const Q=y(K);if(Q&&!isSymlinkSync(K))throw Error(`Expected monorepo plugin link at ${K} to be a symlink`);X.mkdirSync(B.dirname(K),{recursive:!0});const V=S(K,"tmp"),Y=Q?S(K,"bak"):null,Z=I?"junction":"dir";let J=!1;try{X.symlinkSync(q,V,Z);if(Y)X.renameSync(K,Y);X.renameSync(V,K)}catch($){D(V);if(Y&&!y(K))try{X.renameSync(Y,K)}catch{}throw $}return{finalize(){if(J)return;J=!0;if(Y)D(Y)},rollback(){if(J)return;J=!0;D(K);if(Y&&!y(K))try{X.renameSync(Y,K)}catch{}D(V)}}}function readLockFileWithWriter(q=writeLockFile){try{const K=X.readFileSync(getLockFilePath(),"utf-8"),Q=JSON.parse(K);if(!L(Q))return{};const V={};let Y=!1;for(const[Z,J]of Object.entries(Q)){const $=Kq(J);if(!$){Y=!0;continue}V[Z]=$;if(JSON.stringify(J)!==JSON.stringify($))Y=!0}if(Y)try{q(V)}catch{}return V}catch{return{}}}export function readLockFile(){return readLockFileWithWriter(writeLockFile)}function writeLockFileWithFs(q,K=X){const Q=getLockFilePath();K.mkdirSync(B.dirname(Q),{recursive:!0});const V=S(Q,"tmp");try{K.writeFileSync(V,JSON.stringify(q,null,2)+`
+`);K.renameSync(V,Q)}catch(Y){try{K.rmSync(V,{force:!0})}catch{}throw Y}}export function writeLockFile(q){writeLockFileWithFs(q,X)}export function getCommitHash(q){try{return v("git",["rev-parse","HEAD"],{cwd:q,encoding:"utf-8",stdio:["pipe","pipe","pipe"]}).trim()}catch{return}}export function validatePluginStructure(q){const K=[];if(!X.existsSync(q))return{valid:!1,errors:["Plugin directory does not exist"]};const Q=X.readdirSync(q),V=Q.some((Z)=>Z.endsWith(".ts")&&!Z.endsWith(".d.ts")&&!Z.endsWith(".test.ts")),Y=Q.some((Z)=>Z.endsWith(".js")&&!Z.endsWith(".d.js"));if(!V&&!Y)K.push("No command files found in plugin directory. A plugin must contain at least one .ts or .js command file.");if(V){const Z=B.join(q,"package.json");if(!X.existsSync(Z))K.push('Plugin contains .ts files but no package.json. A package.json with "type": "module" and "@jackwener/opencli" peer dependency is required for TS plugins.');else try{if(JSON.parse(X.readFileSync(Z,"utf-8")).type!=="module")K.push('Plugin package.json must have "type": "module" for TypeScript plugins.')}catch{K.push("Plugin package.json is malformed or invalid JSON.")}}return{valid:K.length===0,errors:K}}function Zq(q){const K=B.join(q,"package.json");if(!X.existsSync(K))return!1;try{const Q=JSON.parse(X.readFileSync(K,"utf-8"));return Q.dependencies!=null&&Object.keys(Q.dependencies).length>0}catch{return!1}}function installDependencies(q){const K=B.join(q,"package.json");if(!X.existsSync(K))return;try{v("npm",["install","--omit=dev"],{cwd:q,encoding:"utf-8",stdio:["pipe","pipe","pipe"],...I&&{shell:!0}})}catch(Q){throw new G(`npm install failed in ${q}: ${U(Q)}`,"Check your network connection and npm configuration.")}}function h(q){Gq(q);_q(q)}function s(q){installDependencies(q);h(q)}function postInstallMonorepoLifecycle(q,K){installDependencies(q);for(const Q of K){if(Q!==q&&Zq(Q))installDependencies(Q);h(Q)}}function n(q){const K=validatePluginStructure(q);if(!K.valid)throw new G(`Invalid plugin structure:
+- ${K.errors.join(`
+- `)}`);s(q)}function M(q,K,Q){q[K]={...Q,installedAt:Q.installedAt??new Date().toISOString()}}function o(q,K,Q){p((V)=>{V.track(a(q,K));Q(getCommitHash(K))})}function l(q,K,Q,V,Y){p((Z)=>{if(V){X.mkdirSync(V.parentDir,{recursive:!0});Z.track(a(V.stagingDir,q))}const J=getCommitHash(q);for(const $ of Q){const A=B.join(K,$.name),z=C(q,$.subPath);Z.track(Yq(z,A))}Y?.(J)})}export function installPlugin(q){const K=parseSource(q);if(!K)throw Error(`Invalid plugin source: "${q}"
+Supported formats:
+  github:user/repo
+  github:user/repo/subplugin
+  https://github.com/user/repo
+  https://<host>/<path>/repo.git
+  ssh://git@<host>/<path>/repo.git
+  git@<host>:user/repo.git
+  file:///absolute/path
+  /absolute/path`);const{name:Q,subPlugin:V}=K;if(K.type==="local")return installLocalPlugin(K.localPath,Q);return d(K.cloneUrl,(Y)=>{const Z=F(Y);if(Z?.opencli&&!O(Z.opencli))throw Error(`Plugin requires opencli ${Z.opencli}, but current version is incompatible.`);if(Z&&b(Z))return Jq(Y,K.cloneUrl,Q,Z,V);return $q(Y,K.cloneUrl,Q,Z)})}function $q(q,K,Q,V){const Y=V?.name??Q,Z=B.join(x,Y);if(X.existsSync(Z))throw new G(`Plugin "${Y}" is already installed at ${Z}`,'Use "opencli plugin uninstall" first, or pick a different name.');n(q);o(q,Z,(J)=>{const $=readLockFile();if(J){M($,Y,{source:{kind:"git",url:K},commitHash:J});writeLockFile($)}});return Y}function installLocalPlugin(q,K){if(!X.existsSync(q))throw new G(`Local plugin path does not exist: ${q}`);if(!X.statSync(q).isDirectory())throw new G(`Local plugin path is not a directory: ${q}`);const V=F(q);if(V?.opencli&&!O(V.opencli))throw new G(`Plugin requires opencli ${V.opencli}, but current version is incompatible.`,"Upgrade opencli to a compatible version.");const Y=V?.name??K,Z=B.join(x,Y);if(X.existsSync(Z))throw new G(`Plugin "${Y}" is already installed at ${Z}`,'Use "opencli plugin uninstall" first, or pick a different name.');const J=validatePluginStructure(q);if(!J.valid)throw new G(`Invalid plugin structure:
+- ${J.errors.join(`
+- `)}`);X.mkdirSync(x,{recursive:!0});const $=B.resolve(q),A=I?"junction":"dir";X.symlinkSync($,Z,A);installDependencies(q);h(q);const z=readLockFile(),j=getCommitHash(q);M(z,Y,{source:{kind:"local",path:$},commitHash:j??"local"});writeLockFile(z);return Y}function Xq(q,K,Q,V){const Y=X.realpathSync(K),Z=validatePluginStructure(Y);if(!Z.valid)T.warn(`Plugin "${q}" structure invalid:
+- ${Z.errors.join(`
+- `)}`);s(Y);M(Q,q,{source:V?.source??{kind:"local",path:Y},commitHash:getCommitHash(Y)??"local",installedAt:V?.installedAt??new Date().toISOString(),updatedAt:new Date().toISOString()});writeLockFile(Q)}function Jq(q,K,Q,V,Y){const Z=getMonoreposDir(),J=B.join(Z,Q),$=X.existsSync(J),A=$?J:q,z=$?F(J):V;if(!z||!b(z))throw new G(`Monorepo manifest missing or invalid at ${A}`);let j=i(z);if(Y){j=j.filter((W)=>W.name===Y);if(j.length===0){if(z.plugins?.[Y])throw new G(`Sub-plugin "${Y}" is disabled in the manifest.`);throw new G(`Sub-plugin "${Y}" not found in monorepo. Available: ${Object.keys(z.plugins??{}).join(", ")}`)}}const w=[],H=readLockFile(),N=[];X.mkdirSync(x,{recursive:!0});for(const{name:W,entry:_}of j){if(_.opencli&&!O(_.opencli)){T.warn(`Skipping "${W}": requires opencli ${_.opencli}`);continue}let E;try{E=C(A,_.path)}catch{T.warn(`Skipping "${W}": path "${_.path}" escapes repo root.`);continue}if(!X.existsSync(E)){T.warn(`Skipping "${W}": path "${_.path}" not found in repo.`);continue}const m=validatePluginStructure(E);if(!m.valid){T.warn(`Skipping "${W}": invalid structure — ${m.errors.join(", ")}`);continue}const g=B.join(x,W);if(X.existsSync(g)){T.warn(`Skipping "${W}": already installed at ${g}`);continue}N.push({name:W,entry:_})}if(N.length===0)return w;const R=N.map(({name:W,entry:_})=>({name:W,subPath:_.path}));if($)postInstallMonorepoLifecycle(J,N.map((W)=>C(J,W.entry.path)));else postInstallMonorepoLifecycle(q,N.map((W)=>C(q,W.entry.path)));l(J,x,R,$?void 0:{stagingDir:q,parentDir:Z},(W)=>{for(const{name:_,entry:E}of N){if(W)M(H,_,{source:{kind:"monorepo",url:K,repoName:Q,subPath:E.path},commitHash:W});w.push(_)}writeLockFile(H)});return w}function Bq(q,K,Q,V,Y){const Z=[];for(const[J,$]of Object.entries(K)){if($.source.kind!=="monorepo"||$.source.repoName!==q)continue;const A=Q.plugins?.[J];if(!A||A.disabled)throw Error(`Installed sub-plugin "${J}" no longer exists in ${V}`);if(A.opencli&&!O(A.opencli))throw Error(`Sub-plugin "${J}" requires opencli ${A.opencli}`);const z=C(Y,A.path),j=validatePluginStructure(z);if(!j.valid)throw Error(`Updated sub-plugin "${J}" is invalid:
+- ${j.errors.join(`
+- `)}`);Z.push({name:J,lockEntry:$,manifestEntry:A})}return Z}function Aq(q,K,Q,V,Y){for(const Z of K){if(!Y)continue;M(q,Z.name,{...Z.lockEntry,source:{kind:"monorepo",url:Q,repoName:V,subPath:Z.manifestEntry.path},commitHash:Y,updatedAt:new Date().toISOString()})}}function zq(q,K,Q,V,Y){if(!Y)return;M(q,K,{source:{kind:"git",url:Q},commitHash:Y,installedAt:V?.installedAt??new Date().toISOString(),updatedAt:new Date().toISOString()})}export function uninstallPlugin(q){const K=B.join(x,q);if(!y(K))throw Error(`Plugin "${q}" is not installed.`);const Q=readLockFile(),V=Q[q];if(isSymlinkSync(K))X.unlinkSync(K);else X.rmSync(K,{recursive:!0,force:!0});if(V?.source.kind==="monorepo"){delete Q[q];const Z=V.source.repoName;if(!Object.values(Q).some(($)=>$.source.kind==="monorepo"&&$.source.repoName===Z)){const $=B.join(getMonoreposDir(),Z);try{X.rmSync($,{recursive:!0,force:!0})}catch{}}}else if(Q[q])delete Q[q];writeLockFile(Q)}function isSymlinkSync(q){try{return X.lstatSync(q).isSymbolicLink()}catch{return!1}}export function updatePlugin(q){const K=B.join(x,q);if(!X.existsSync(K))throw Error(`Plugin "${q}" is not installed.`);const Q=readLockFile(),V=Q[q],Y=resolvePluginSource(V,K);if(Y?.kind==="local"){Xq(q,K,Q,V);return}if(Y?.kind==="monorepo"){const J=B.join(getMonoreposDir(),Y.repoName),$=Y.repoName,A=Y.url;d(A,(z)=>{const j=F(z);if(!j||!b(j))throw Error(`Updated source is no longer a monorepo: ${A}`);if(j.opencli&&!O(j.opencli))throw Error(`Plugin requires opencli ${j.opencli}, but current version is incompatible.`);const w=Bq($,Q,j,A,z);if(w.length>0)postInstallMonorepoLifecycle(z,w.map((H)=>C(z,H.manifestEntry.path)));l(J,x,w.map((H)=>({name:H.name,subPath:H.manifestEntry.path})),{stagingDir:z,parentDir:B.dirname(J)},(H)=>{Aq(Q,w,A,$,H);writeLockFile(Q)})});return}const Z=Vq(V,K);d(Z,(J)=>{const $=F(J);if($&&b($))throw Error(`Updated source is now a monorepo: ${Z}`);if($?.opencli&&!O($.opencli))throw Error(`Plugin requires opencli ${$.opencli}, but current version is incompatible.`);n(J);o(J,K,(A)=>{zq(Q,q,Z,Q[q],A);if(A)writeLockFile(Q)})})}export function updateAllPlugins(){return listPlugins().map((q)=>{try{updatePlugin(q.name);return{name:q.name,success:!0}}catch(K){return{name:q.name,success:!1,error:U(K)}}})}export function listPlugins(){if(!X.existsSync(x))return[];const q=X.readdirSync(x,{withFileTypes:!0}),K=readLockFile(),Q=[];for(const V of q){const Y=B.join(x,V.name);if(!(V.isDirectory()||isSymlinkSync(Y)))continue;const J=jq(Y),$=K[V.name],A=F(Y);let z=A?.description,j=A?.version;if($?.source.kind==="monorepo"&&!z){const H=B.join(getMonoreposDir(),$.source.repoName),R=F(H)?.plugins?.[V.name];if(R){z=z??R.description;j=j??R.version}}const w=resolveStoredPluginSource($,Y);Q.push({name:V.name,path:Y,commands:J,source:w,version:j??$?.commitHash?.slice(0,7),installedAt:$?.installedAt,monorepoName:$?.source.kind==="monorepo"?$.source.repoName:void 0,description:z})}return Q}function jq(q){try{const K=X.readdirSync(q);return[...new Set(K.filter((V)=>V.endsWith(".ts")&&!V.endsWith(".d.ts")&&!V.endsWith(".test.ts")||V.endsWith(".js")&&!V.endsWith(".d.js")).map((V)=>B.basename(V,B.extname(V))))]}catch{return[]}}function Wq(q){try{return v("git",["config","--get","remote.origin.url"],{cwd:q,encoding:"utf-8",stdio:["pipe","pipe","pipe"]}).trim()}catch{return}}function parseSource(q){if(q.startsWith("file://"))try{const $=B.resolve(f(q));return{type:"local",localPath:$,name:B.basename($).replace(/^opencli-plugin-/,"")}}catch{return null}if(B.isAbsolute(q)){const $=B.resolve(q);return{type:"local",localPath:$,name:B.basename($).replace(/^opencli-plugin-/,"")}}const K=q.match(/^github:([\w.-]+)\/([\w.-]+)\/([\w.-]+)$/);if(K){const[,$,A,z]=K,j=A.replace(/^opencli-plugin-/,"");return{type:"git",cloneUrl:`https://github.com/${$}/${A}.git`,name:j,subPlugin:z}}const Q=q.match(/^github:([\w.-]+)\/([\w.-]+)$/);if(Q){const[,$,A]=Q,z=A.replace(/^opencli-plugin-/,"");return{type:"git",cloneUrl:`https://github.com/${$}/${A}.git`,name:z}}const V=q.match(/^https?:\/\/github\.com\/([\w.-]+)\/([\w.-]+?)(?:\.git)?$/);if(V){const[,$,A]=V,z=A.replace(/^opencli-plugin-/,"");return{type:"git",cloneUrl:`https://github.com/${$}/${A}.git`,name:z}}const Y=q.match(/^ssh:\/\/[^/]+\/(.*?)(?:\.git)?$/);if(Y){const j=Y[1].split("/").pop().replace(/^opencli-plugin-/,"");return{type:"git",cloneUrl:q,name:j}}const Z=q.match(/^git@[^:]+:(.+?)(?:\.git)?$/);if(Z){const j=Z[1].split("/").pop().replace(/^opencli-plugin-/,"");return{type:"git",cloneUrl:q,name:j}}const J=q.match(/^https?:\/\/[^/]+\/(.+?)(?:\.git)?$/);if(J){const j=J[1].split("/").pop().replace(/^opencli-plugin-/,"");return{type:"git",cloneUrl:q.endsWith(".git")?q:`${q}.git`,name:j}}return null}function Gq(q){try{const K=resolveHostOpencliRoot(),Q=B.join(q,"node_modules","@jackwener","opencli");if(X.existsSync(Q))X.rmSync(Q,{recursive:!0,force:!0});X.mkdirSync(B.dirname(Q),{recursive:!0});const V=I?"junction":"dir";X.symlinkSync(K,Q,V);T.debug(`Linked host opencli into plugin: ${Q} → ${K}`)}catch(K){T.warn(`Failed to link host opencli into plugin: ${U(K)}`)}}export function resolveEsbuildBin(){const q=resolveHostOpencliRoot();if(I){const Q=B.join(q,"node_modules",".bin","esbuild.cmd");if(X.existsSync(Q))return Q}if(!I)try{const Q=import.meta.resolve("esbuild/package.json");if(Q.startsWith("file://")){const V=f(Q),Y=X.readFileSync(V,"utf8"),Z=JSON.parse(Y);if(Z.bin&&typeof Z.bin==="object"&&Z.bin.esbuild){const J=B.resolve(B.dirname(V),Z.bin.esbuild);if(X.existsSync(J))return J}else if(typeof Z.bin==="string"){const J=B.resolve(B.dirname(V),Z.bin);if(X.existsSync(J))return J}}}catch{}const K=B.join(q,"node_modules",".bin","esbuild");if(X.existsSync(K))return K;try{const V=r(I?"where esbuild":"which esbuild",{encoding:"utf-8",stdio:"pipe"}).trim().split(`
+`)[0].trim();if(V&&X.existsSync(V))return V}catch{}return null}function resolveHostOpencliRoot(q=f(import.meta.url)){let K=B.dirname(q);while(!0){const Q=B.join(K,"package.json");if(X.existsSync(Q))try{if(JSON.parse(X.readFileSync(Q,"utf-8"))?.name==="@jackwener/opencli")return K}catch{}const V=B.dirname(K);if(V===K)break;K=V}return B.resolve(B.dirname(q),"..")}function _q(q){try{const K=resolveEsbuildBin();if(!K){T.warn("esbuild not found. TS plugin files will not be transpiled and may fail to load. Install esbuild (`npm i -g esbuild`) or ensure it is available in the opencli host node_modules.");return}const V=X.readdirSync(q).filter((Y)=>Y.endsWith(".ts")&&!Y.endsWith(".d.ts")&&!Y.endsWith(".test.ts"));for(const Y of V){const Z=Y.replace(/\.ts$/,".js"),J=B.join(q,Z);if(X.existsSync(J))continue;try{v(K,[Y,`--outfile=${Z}`,"--format=esm","--platform=node"],{cwd:q,encoding:"utf-8",stdio:["pipe","pipe","pipe"],...I&&{shell:!0}});T.debug(`Transpiled plugin file: ${Y} → ${Z}`)}catch($){T.warn(`Failed to transpile ${Y}: ${U($)}`)}}}catch(K){T.warn(`TS transpilation setup failed: ${U(K)}`)}}export{resolveHostOpencliRoot as _resolveHostOpencliRoot,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,resolvePluginSource as _resolvePluginSource,resolveStoredPluginSource as _resolveStoredPluginSource,toStoredPluginSource as _toStoredPluginSource,toLocalPluginSource as _toLocalPluginSource};

package/dist/src/plugin.test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Tests for plugin management: install, uninstall, list, and lock file support.
+ */
+export {};

package/dist/src/rate-limit.d.ts

@@ -0,0 +1,15 @@
+export interface RateLimitRule {
+    command: string;
+    limit: number;
+    windowMs: number;
+}
+export interface RateLimitOptions {
+    configPath?: string;
+    statePath?: string;
+    now?: number;
+}
+export declare function getRateLimitConfigPath(homeDir?: string): string;
+export declare function getRateLimitStatePath(homeDir?: string): string;
+export declare function enforceRateLimit(command: string, opts?: RateLimitOptions): void;
+export declare function findRateLimitRule(command: string, configPath?: string): RateLimitRule | null;
+export declare function loadRateLimitRules(configPath?: string): RateLimitRule[];

package/dist/src/rate-limit.js

@@ -0,0 +1,2 @@
+import*as m from"node:fs";import*as p from"node:os";import*as f from"node:path";import $ from"js-yaml";import{ConfigError as s,RateLimitError as v,getErrorMessage as S}from"./errors.js";import{isRecord as l}from"./utils.js";const g="rate-limits.yaml",x="rate-limit-state.json";export function getRateLimitConfigPath(t=p.homedir()){return f.join(t,".opencli",g)}export function getRateLimitStatePath(t=p.homedir()){return f.join(t,".opencli",x)}export function enforceRateLimit(t,e={}){const r=e.configPath??getRateLimitConfigPath(),n=findRateLimitRule(t,r);if(!n)return;const o=e.statePath??getRateLimitStatePath(),i=e.now??Date.now(),a=M(o),c=Array.isArray(a.commands[t])?a.commands[t]:[],h=i-n.windowMs,u=c.filter((d)=>Number.isFinite(d)&&d>h);if(u.length>=n.limit){const d=Math.min(...u),b=Math.max(0,d+n.windowMs-i);a.commands[t]=u;y(o,a);throw new v(t,b,r)}a.commands[t]=[...u,i];y(o,a)}export function findRateLimitRule(t,e=getRateLimitConfigPath()){return loadRateLimitRules(e).find((n)=>n.command===t)??null}export function loadRateLimitRules(t=getRateLimitConfigPath()){if(!m.existsSync(t))return[];let e;try{e=$.load(m.readFileSync(t,"utf-8"))??{}}catch(n){throw new s(`Failed to parse ${t}: ${S(n)}`,"Fix the YAML syntax or remove the file to disable command rate limits.")}if(!l(e))throw new s(`Invalid ${t}: root value must be an object with a rules array.`);const r=e.rules;if(r===void 0)return[];if(!Array.isArray(r))throw new s(`Invalid ${t}: rules must be an array.`);return r.map((n,o)=>F(n,o,t))}function F(t,e,r){const n=`${r} rules[${e}]`;if(!l(t))throw new s(`Invalid ${n}: rule must be an object.`);const o=typeof t.command==="string"?t.command.trim():"";if(!o)throw new s(`Invalid ${n}: command must be a non-empty string.`);const i=Number(t.limit);if(!Number.isInteger(i)||i<=0)throw new s(`Invalid ${n}: limit must be a positive integer.`);if(typeof t.window!=="string"&&typeof t.window!=="number")throw new s(`Invalid ${n}: window must be a duration like 10m, 1h, or 500ms.`);return{command:o,limit:i,windowMs:I(t.window,`${n}.window`)}}function I(t,e){const r=String(t).trim(),n=/^(\d+(?:\.\d+)?)(ms|s|m|h)?$/.exec(r);if(!n)throw new s(`Invalid ${e}: expected a duration like 10m, 1h, or 500ms.`);const o=Number.parseFloat(n[1]),i=n[2]??"ms",c=Math.round(o*(i==="h"?3600000:i==="m"?60000:i==="s"?1000:1));if(!Number.isFinite(c)||c<=0)throw new s(`Invalid ${e}: duration must be greater than zero.`);return c}function M(t){if(!m.existsSync(t))return w();try{const e=JSON.parse(m.readFileSync(t,"utf-8"));if(!l(e)||!l(e.commands))return w();const r={};for(const[n,o]of Object.entries(e.commands)){if(!Array.isArray(o))continue;r[n]=o.filter((i)=>typeof i==="number"&&Number.isFinite(i))}return{version:1,commands:r}}catch{return w()}}function y(t,e){m.mkdirSync(f.dirname(t),{recursive:!0});const r=`${t}.${process.pid}.${Date.now()}.tmp`;m.writeFileSync(r,JSON.stringify(e,null,2)+`
+`,"utf-8");m.renameSync(r,t)}function w(){return{version:1,commands:{}}}

package/dist/src/rate-limit.test.d.ts

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

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

@@ -0,0 +1,13 @@
+/**
+ * Public API for opencli plugins.
+ *
+ * TS plugins should import from '@jackwener/opencli/registry' which resolves to
+ * this file. It re-exports ONLY the core registration API — no serialization,
+ * no transitive side-effects — to avoid circular dependency deadlocks when
+ * plugins are dynamically imported during discoverPlugins().
+ */
+export { cli, Strategy, getRegistry, fullName, registerCommand } from './registry.js';
+export type { CliCommand, Arg, CliOptions, CommandArgs, SiteSessionMode } 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/registry-api.js

@@ -0,0 +1 @@
+export{cli,Strategy,getRegistry,fullName,registerCommand}from"./registry.js";export{onStartup,onBeforeExecute,onAfterExecute}from"./hooks.js";

package/dist/src/registry.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Core registry: Strategy enum, Arg/CliCommand interfaces, cli() registration.
+ */
+import type { IPage } from './types.js';
+export declare enum Strategy {
+    PUBLIC = "public",
+    LOCAL = "local",
+    COOKIE = "cookie",
+    INTERCEPT = "intercept",
+    UI = "ui"
+}
+export interface Arg {
+    name: string;
+    type?: string;
+    default?: unknown;
+    required?: boolean;
+    valueRequired?: boolean;
+    positional?: boolean;
+    help?: string;
+    choices?: string[];
+}
+export type CommandArgs = Record<string, any>;
+export type BrowserCommandFunc = (page: IPage, kwargs: CommandArgs, debug?: boolean) => Promise<unknown>;
+export type NonBrowserCommandFunc = (kwargs: CommandArgs, debug?: boolean) => Promise<unknown>;
+export type CommandAccess = 'read' | 'write';
+export type SiteSessionMode = 'ephemeral' | 'persistent';
+export interface AuthStatusMetadata {
+    quickCheck?: BrowserCommandFunc;
+    refresh?: BrowserCommandFunc;
+    /** [pp-only] 标记「快检必须真实导航页面」的站点（jike/discord：登录态在
+     *  localStorage/IndexedDB，cookie 罐里没有登录信号，走不了免导航快检）。
+     *  置为 true 时，后台批量/单站 `auth status`（quick）**不再开页探测**，直接返回
+     *  status='unknown' / checked='navigation_required'——由调用方（桌面）改成按需探测
+     *  （用户打开该平台或发布前才 `--full` whoami），彻底消除 20s 轮询反复弹这两个页。
+     *  不缓存：`--full` whoami 仍会真实导航，语义与登出即时可见一致。 */
+    quickCheckRequiresNavigation?: boolean;
+}
+interface BaseCliCommand {
+    site: string;
+    name: string;
+    aliases?: string[];
+    description: string;
+    access: CommandAccess;
+    /** Canonical invocation shown in agent-facing help. Generated when omitted. */
+    example?: string;
+    domain?: string;
+    strategy?: Strategy;
+    args: Arg[];
+    columns?: string[];
+    pipeline?: Record<string, unknown>[];
+    /** Origin of this command: 'yaml', 'ts', or plugin name. */
+    source?: string;
+    footerExtra?: (kwargs: CommandArgs) => string | undefined;
+    validateArgs?: (kwargs: CommandArgs) => void;
+    /**
+     * Control pre-navigation and browser-session requirement.
+     *
+     * After normalizeCommand() expands strategy, this field carries the
+     * resolved runtime intent:
+     *
+     * - `undefined`: no pre-navigation, browser session decided by pipeline steps
+     * - `false`: explicitly skip pre-navigation (adapter handles its own navigation)
+     * - `true`: needs authenticated browser context but no specific pre-nav URL
+     *   (e.g. INTERCEPT/UI adapters, or COOKIE without domain)
+     * - `string`: pre-navigate to this URL before running the adapter
+     *   (e.g. `'https://x.com'` for COOKIE strategy with domain)
+     *
+     * Adapter authors can set this explicitly to override the strategy-based default.
+     */
+    navigateBefore?: boolean | string;
+    /** Site session lifecycle for adapter commands. */
+    siteSession?: SiteSessionMode;
+    /** Default browser window mode for commands whose UX requires visibility. */
+    defaultWindowMode?: 'foreground' | 'background';
+    /** Override the default CLI output format when the user does not pass -f/--format. */
+    defaultFormat?: 'table' | 'plain' | 'json' | 'yaml' | 'yml' | 'md' | 'markdown' | 'csv';
+    /** Optional auth-status metadata attached by shared auth adapters. */
+    authStatus?: AuthStatusMetadata;
+}
+export interface BrowserCliCommand extends BaseCliCommand {
+    /** Browser commands receive an IPage. Omitted means true after normalization. */
+    browser?: true;
+    func?: BrowserCommandFunc;
+}
+export interface NonBrowserCliCommand extends BaseCliCommand {
+    /** Non-browser commands do not receive a page argument. */
+    browser: false;
+    func?: NonBrowserCommandFunc;
+}
+export type CliCommand = BrowserCliCommand | NonBrowserCliCommand;
+type RawCliCommand = BaseCliCommand & {
+    browser?: boolean;
+    func?: BrowserCommandFunc | NonBrowserCommandFunc;
+};
+/** Internal extension for lazy-loaded TS modules (not exposed in public API) */
+export type InternalCliCommand = CliCommand & {
+    _lazy?: boolean;
+    _modulePath?: string;
+};
+type RequiredCliOptions = {
+    site: string;
+    name: string;
+    access: CommandAccess;
+    description?: string;
+    args?: Arg[];
+};
+type BrowserStrategy = Exclude<Strategy, Strategy.PUBLIC | Strategy.LOCAL>;
+type BrowserCliOptions = Partial<Omit<BrowserCliCommand, 'args' | 'description' | 'browser' | 'strategy'>> & RequiredCliOptions & ({
+    browser: true;
+    strategy?: Strategy;
+} | {
+    browser?: true;
+    strategy?: BrowserStrategy;
+});
+type NonBrowserCliOptions = Partial<Omit<NonBrowserCliCommand, 'args' | 'description'>> & RequiredCliOptions & ({
+    browser: false;
+} | {
+    strategy: Strategy.PUBLIC | Strategy.LOCAL;
+    browser?: false;
+});
+export type CliOptions = BrowserCliOptions | NonBrowserCliOptions;
+declare global {
+    var __opencli_registry__: Map<string, CliCommand> | undefined;
+}
+export declare function cli(opts: CliOptions): CliCommand;
+export declare function getRegistry(): Map<string, CliCommand>;
+export declare function fullName(cmd: Pick<BaseCliCommand, 'site' | 'name'>): string;
+export declare function strategyLabel(cmd: CliCommand): string;
+export declare function registerCommand(cmd: RawCliCommand): void;
+export {};

package/dist/src/registry.js

@@ -0,0 +1 @@
+export var Strategy;(function(j){j.PUBLIC="public";j.LOCAL="local";j.COOKIE="cookie";j.INTERCEPT="intercept";j.UI="ui"})(Strategy||(Strategy={}));const H=globalThis.__opencli_registry__??=new Map;export function cli(j){const q={site:j.site,name:j.name,aliases:j.aliases,description:j.description??"",access:j.access,example:j.example,domain:j.domain,strategy:j.strategy,browser:j.browser,args:j.args??[],columns:j.columns,func:j.func,pipeline:j.pipeline,footerExtra:j.footerExtra,validateArgs:j.validateArgs,navigateBefore:j.navigateBefore,siteSession:j.siteSession,defaultWindowMode:j.defaultWindowMode,defaultFormat:j.defaultFormat,authStatus:j.authStatus};registerCommand(q);return H.get(fullName(q))}export function getRegistry(){return H}export function fullName(j){return`${j.site}/${j.name}`}export function strategyLabel(j){return j.strategy??Strategy.PUBLIC}function I(j){J(j);L(j);const q=j.strategy??(j.browser===!1?Strategy.PUBLIC:Strategy.COOKIE),F=j.browser??(q!==Strategy.PUBLIC&&q!==Strategy.LOCAL);let D=j.navigateBefore;if(D===void 0){if(q===Strategy.COOKIE&&j.domain)D=`https://${j.domain}`;else if(q!==Strategy.PUBLIC&&q!==Strategy.LOCAL)D=!0}return F?{...j,strategy:q,browser:!0,navigateBefore:D}:{...j,strategy:q,browser:!1,navigateBefore:D}}function J(j){if(j.access==="read"||j.access==="write")return;const q=`${j.site}/${j.name}`;throw Error(`Command ${q} must declare access: 'read' | 'write'`)}function L(j){if(j.siteSession===void 0)return;const q=`${j.site}/${j.name}`;if(j.siteSession!=="ephemeral"&&j.siteSession!=="persistent")throw Error(`Command ${q} siteSession must be one of: ephemeral, persistent`)}export function registerCommand(j){const q=I(j),F=fullName(q),D=H.get(F);if(D?.aliases)for(const E of D.aliases)H.delete(`${D.site}/${E}`);const G=M(q.aliases,q.name);q.aliases=G.length>0?G:void 0;H.set(F,q);for(const E of G)H.set(`${q.site}/${E}`,q)}function M(j,q){if(!Array.isArray(j)||j.length===0)return[];const F=new Set,D=[];for(const G of j){const E=typeof G==="string"?G.trim():"";if(!E||E===q||F.has(E))continue;F.add(E);D.push(E)}return D}

package/dist/src/registry.test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Tests for registry.ts: Strategy enum, cli() registration, helpers.
+ */
+export {};

package/dist/src/runtime-detect.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Runtime detection — identify whether opencli is running under Node.js or Bun.
+ *
+ * Bun injects `globalThis.Bun` at startup, making detection trivial.
+ * This module centralises the check so other code can adapt behaviour
+ * (e.g. logging, diagnostics) without littering runtime sniffing everywhere.
+ */
+export type Runtime = 'bun' | 'node';
+export declare const MIN_SUPPORTED_NODE_MAJOR = 20;
+/**
+ * Detect the current JavaScript runtime.
+ */
+export declare function detectRuntime(): Runtime;
+/**
+ * Return a human-readable version string for the current runtime.
+ * Examples: "v22.13.0" (Node), "1.1.42" (Bun)
+ */
+export declare function getRuntimeVersion(): string;
+/**
+ * Return a combined label like "node v22.13.0" or "bun 1.1.42".
+ */
+export declare function getRuntimeLabel(): string;
+/**
+ * Parse a Node.js version string like "v22.13.0" and return its major version.
+ * Returns null for non-Node or malformed inputs.
+ */
+export declare function parseNodeMajor(version: string): number | null;
+/**
+ * Whether the given Node.js version satisfies the current minimum support policy.
+ */
+export declare function isSupportedNodeVersion(version?: string): boolean;

package/dist/src/runtime-detect.js

@@ -0,0 +1 @@
+export const MIN_SUPPORTED_NODE_MAJOR=20;export function detectRuntime(){return globalThis.Bun!==void 0?"bun":"node"}export function getRuntimeVersion(){const k=globalThis.Bun;return k?k.version:process.version}export function getRuntimeLabel(){return`${detectRuntime()} ${getRuntimeVersion()}`}export function parseNodeMajor(k){const q=/^v?(\d+)\./.exec(String(k).trim());if(!q)return null;const w=Number(q[1]);return Number.isInteger(w)?w:null}export function isSupportedNodeVersion(k=process.version){const q=parseNodeMajor(k);return q!==null&&q>=MIN_SUPPORTED_NODE_MAJOR}

package/dist/src/runtime-detect.test.d.ts

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

package/dist/src/runtime.d.ts

@@ -0,0 +1,57 @@
+import type { IPage } from './types.js';
+import { DEFAULT_BROWSER_COMMAND_TIMEOUT, DEFAULT_BROWSER_CONNECT_TIMEOUT } from './browser/config.js';
+export { DEFAULT_BROWSER_COMMAND_TIMEOUT, DEFAULT_BROWSER_CONNECT_TIMEOUT };
+/**
+ * Returns the appropriate browser factory based on site type.
+ * Uses CDPBridge for registered Electron apps, otherwise BrowserBridge.
+ */
+export declare function getBrowserFactory(site?: string): new () => IBrowserFactory;
+export type BrowserWindowMode = 'foreground' | 'background';
+export type BrowserSurface = 'browser' | 'adapter';
+/**
+ * Timeout with seconds unit. Used for high-level command timeouts.
+ */
+export declare function runWithTimeout<T>(promise: Promise<T>, opts: {
+    timeout: number;
+    label?: string;
+    hint?: string;
+}): Promise<T>;
+/**
+ * Timeout with milliseconds unit. Used for low-level internal timeouts.
+ * Accepts a factory function to create the rejection error, keeping this
+ * utility decoupled from specific error types.
+ */
+export declare function withTimeoutMs<T>(promise: Promise<T>, timeoutMs: number, makeError?: string | (() => Error)): Promise<T>;
+/** Interface for browser factory (BrowserBridge or test mocks) */
+export interface IBrowserFactory {
+    connect(opts?: {
+        timeout?: number;
+        session?: string;
+        cdpEndpoint?: string;
+        contextId?: string;
+        idleTimeout?: number;
+        windowMode?: BrowserWindowMode;
+        surface?: BrowserSurface;
+        siteSession?: 'ephemeral' | 'persistent';
+        initScript?: string;
+        proxyAuth?: {
+            username: string;
+            password: string;
+        };
+    }): Promise<IPage>;
+    close(): Promise<void>;
+}
+export declare function browserSession<T>(BrowserFactory: new () => IBrowserFactory, fn: (page: IPage) => Promise<T>, opts?: {
+    session?: string;
+    cdpEndpoint?: string;
+    contextId?: string;
+    idleTimeout?: number;
+    windowMode?: BrowserWindowMode;
+    surface?: BrowserSurface;
+    siteSession?: 'ephemeral' | 'persistent';
+    initScript?: string;
+    proxyAuth?: {
+        username: string;
+        password: string;
+    };
+}): Promise<T>;

package/dist/src/runtime.js

@@ -0,0 +1 @@
+import{BrowserBridge as X,CDPBridge as Y}from"./browser/index.js";import{TimeoutError as Z}from"./errors.js";import{isElectronApp as $}from"./electron-apps.js";import{DEFAULT_BROWSER_COMMAND_TIMEOUT,DEFAULT_BROWSER_CONNECT_TIMEOUT}from"./browser/config.js";export{DEFAULT_BROWSER_COMMAND_TIMEOUT,DEFAULT_BROWSER_CONNECT_TIMEOUT};export function getBrowserFactory(z){if(z&&$(z))return Y;return X}export async function runWithTimeout(z,G){const q=G.label??"Operation";return withTimeoutMs(z,G.timeout*1000,()=>new Z(q,G.timeout,G.hint))}export function withTimeoutMs(z,G,q="Operation timed out"){const H=typeof q==="string"?()=>Error(q):q;return new Promise((J,Q)=>{const V=setTimeout(()=>Q(H()),G);z.then((K)=>{clearTimeout(V);J(K)},(K)=>{clearTimeout(V);Q(K)})})}export async function browserSession(z,G,q={}){const H=new z;try{const J=await H.connect({timeout:DEFAULT_BROWSER_CONNECT_TIMEOUT,session:q.session,cdpEndpoint:q.cdpEndpoint,contextId:q.contextId,idleTimeout:q.idleTimeout,windowMode:q.windowMode,surface:q.surface,siteSession:q.siteSession,initScript:q.initScript,proxyAuth:q.proxyAuth});return await G(J)}finally{await H.close().catch(()=>{})}}

package/dist/src/scripts/framework.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Injected script for detecting frontend frameworks (Vue, React, Next, Nuxt, etc.)
+ *
+ * Serialized via `.toString()` and evaluated in the page context. Types here are
+ * only for the TS boundary — see scripts/store.ts for the same pattern.
+ */
+export declare function detectFramework(): Record<string, boolean>;

package/dist/src/scripts/framework.js

@@ -0,0 +1 @@
+export function detectFramework(){const e={};try{const t=document.querySelector("#app"),r=window;e.vue3=!!(t&&t.__vue_app__);e.vue2=!!(t&&t.__vue__);e.react=!!r.__REACT_DEVTOOLS_GLOBAL_HOOK__||!!document.querySelector("[data-reactroot]");e.nextjs=!!r.__NEXT_DATA__;e.nuxt=!!r.__NUXT__;if(e.vue3&&t?.__vue_app__){const _=t.__vue_app__.config?.globalProperties;e.pinia=!!(_&&_.$pinia);e.vuex=!!(_&&_.$store)}}catch{}return e}

package/dist/src/scripts/interact.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Injected script for interactive fuzzing (clicking elements to trigger lazy loading)
+ */
+export declare function interactFuzz(): Promise<number>;

package/dist/src/scripts/interact.js

@@ -0,0 +1 @@
+export async function interactFuzz(){const q=(f)=>new Promise((h)=>setTimeout(h,f)),u=Array.from(document.querySelectorAll('button, [role="button"], [role="tab"], .tab, .btn, a[href="javascript:void(0)"], a[href="#"]')).slice(0,15);let j=0;for(const f of u)try{const h=f.getBoundingClientRect();if(h.width>0&&h.height>0){f.dispatchEvent(new MouseEvent("click",{bubbles:!0,cancelable:!0,view:window}));j++;await q(300)}}catch{}return j}

package/dist/src/scripts/store.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Injected script for discovering Pinia or Vuex stores and their actions/state representations.
+ *
+ * This function is serialized via `.toString()` and evaluated inside the page context,
+ * so the types below only exist at the TS boundary — the runtime shapes are whatever
+ * Pinia/Vuex put on the Vue app. We use narrow structural types for the fields we touch.
+ */
+export declare function discoverStores(): {
+    type: string;
+    id: string;
+    actions: string[];
+    stateKeys: string[];
+}[];

package/dist/src/scripts/store.js

@@ -0,0 +1 @@
+export function discoverStores(){const s=[];try{const c=document.querySelector("#app");if(!c?.__vue_app__)return s;const r=c.__vue_app__.config?.globalProperties,a=r?.$pinia;if(a?._s)a._s.forEach((o,n)=>{const t=[],i=[];for(const e in o)try{if(e.startsWith("$")||e.startsWith("_"))continue;if(typeof o[e]==="function")t.push(e);else i.push(e)}catch{}s.push({type:"pinia",id:n,actions:t.slice(0,20),stateKeys:i.slice(0,15)})});const p=r?.$store;if(p?._modules?.root?._children){const o=p._modules.root._children;for(const[n,t]of Object.entries(o)){const i=Object.keys(t._rawModule?.actions??{}).slice(0,20),e=Object.keys(t.state??{}).slice(0,15);s.push({type:"vuex",id:n,actions:i,stateKeys:e})}}}catch{}return s}