@nexrall/code-core 1.0.1 → 1.1.0

package/dist/index.d.ts

@@ -11,4 +11,5 @@ export * from './commands/loader';
 export * from './agent/agentTypes';
 export * from './permissions/rules';
 export * from './plugins/index';
+export * from './plugins/installer';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC"}

package/dist/index.js

@@ -27,4 +27,5 @@ __exportStar(require("./commands/loader"), exports);
 __exportStar(require("./agent/agentTypes"), exports);
 __exportStar(require("./permissions/rules"), exports);
 __exportStar(require("./plugins/index"), exports);
+__exportStar(require("./plugins/installer"), exports);
 //# sourceMappingURL=index.js.map

package/dist/plugins/installer.d.ts

@@ -0,0 +1,65 @@
+export interface PluginSource {
+    kind: 'github' | 'local';
+    /** e.g. "owner/repo" (github) or absolute dir (local) */
+    repo: string;
+    /** branch / tag / sha — defaults to HEAD */
+    ref?: string;
+    /** subdirectory inside the repo that is the plugin root */
+    subdir?: string;
+    /** the original user-supplied spec (for receipts / display) */
+    raw: string;
+}
+export interface PluginInspection {
+    commands: string[];
+    agents: string[];
+    hasHooks: boolean;
+    hasMcp: boolean;
+    meta: {
+        name?: string;
+        version?: string;
+        description?: string;
+    };
+}
+export interface InstallReceipt {
+    source: string;
+    kind: 'github' | 'local';
+    ref?: string;
+    subdir?: string;
+    installedAt: string;
+}
+export interface InstallResult {
+    name: string;
+    dir: string;
+    scope: 'project' | 'global';
+    inspection: PluginInspection;
+}
+/** Parse a user-supplied plugin spec into a structured source. Throws on junk. */
+export declare function parsePluginSource(spec: string): PluginSource;
+/** What does this plugin contain? Callers must warn on hasHooks/hasMcp. */
+export declare function inspectPluginDir(dir: string): PluginInspection;
+export interface InstallOptions {
+    /** 'global' (default) → ~/.nexrall/plugins; 'project' → <workDir>/.nexrall/plugins */
+    scope?: 'project' | 'global';
+    workDir?: string;
+    /** Override the installed directory name (defaults to plugin.json name, subdir, or repo name). */
+    name?: string;
+    /** Overwrite an existing plugin of the same name. */
+    force?: boolean;
+    /**
+     * Called after inspection, before finalising. Return false to abort.
+     * Callers should surface hooks/MCP warnings here.
+     */
+    confirm?: (inspection: PluginInspection, name: string) => Promise<boolean> | boolean;
+}
+export declare function installPlugin(spec: string, opts?: InstallOptions): Promise<InstallResult>;
+export declare function readReceipt(pluginDir: string): InstallReceipt | null;
+export declare function removePlugin(name: string, opts?: {
+    scope?: 'project' | 'global';
+    workDir?: string;
+}): string;
+export declare function updatePlugin(name: string, opts?: {
+    scope?: 'project' | 'global';
+    workDir?: string;
+    confirm?: InstallOptions['confirm'];
+}): Promise<InstallResult>;
+//# sourceMappingURL=installer.d.ts.map

package/dist/plugins/installer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"installer.d.ts","sourceRoot":"","sources":["../../src/plugins/installer.ts"],"names":[],"mappings":"AA4BA,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC;IACzB,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACjE;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,SAAS,GAAG,QAAQ,CAAC;IAC5B,UAAU,EAAE,gBAAgB,CAAC;CAC9B;AAMD,kFAAkF;AAClF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CA+C5D;AAYD,2EAA2E;AAC3E,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAiB9D;AAyDD,MAAM,WAAW,cAAc;IAC7B,sFAAsF;IACtF,KAAK,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kGAAkG;IAClG,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,UAAU,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;CACtF;AAQD,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,aAAa,CAAC,CA+EnG;AAED,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAOpE;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,MAAM,CAYhH;AAED,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,cAAc,CAAC,SAAS,CAAC,CAAA;CAAO,GACjG,OAAO,CAAC,aAAa,CAAC,CAexB"}

package/dist/plugins/installer.js

@@ -0,0 +1,300 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parsePluginSource = parsePluginSource;
+exports.inspectPluginDir = inspectPluginDir;
+exports.installPlugin = installPlugin;
+exports.readReceipt = readReceipt;
+exports.removePlugin = removePlugin;
+exports.updatePlugin = updatePlugin;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const child_process_1 = require("child_process");
+const RECEIPT_FILE = '_install.json';
+// ─── Source parsing ───────────────────────────────────────────────────────────
+/** Parse a user-supplied plugin spec into a structured source. Throws on junk. */
+function parsePluginSource(spec) {
+    const raw = spec.trim();
+    if (!raw)
+        throw new Error('Empty plugin source.');
+    // Local directory: ./x, ../x, /abs, ~/x
+    if (raw.startsWith('./') || raw.startsWith('../') || raw.startsWith('/') || raw.startsWith('~/')) {
+        const abs = path.resolve(raw.replace(/^~(?=\/)/, os.homedir()));
+        return { kind: 'local', repo: abs, raw };
+    }
+    // Full GitHub URL → strip to path
+    let rest = raw;
+    const urlMatch = /^https?:\/\/(?:www\.)?github\.com\/(.+)$/i.exec(rest);
+    if (urlMatch)
+        rest = urlMatch[1];
+    rest = rest.replace(/\.git$/, '').replace(/\/+$/, '');
+    // ref via #
+    let ref;
+    const hashIdx = rest.indexOf('#');
+    if (hashIdx !== -1) {
+        ref = rest.slice(hashIdx + 1) || undefined;
+        rest = rest.slice(0, hashIdx);
+    }
+    const parts = rest.split('/').filter(Boolean);
+    if (parts.length < 2) {
+        throw new Error(`Invalid plugin source "${spec}". Use owner/repo, owner/repo#ref, owner/repo/subdir, a GitHub URL, or a local path.`);
+    }
+    // GitHub URLs may include /tree/<ref>/<subdir>
+    if (parts[2] === 'tree' && parts.length >= 4) {
+        ref = ref ?? parts[3];
+        return { kind: 'github', repo: `${parts[0]}/${parts[1]}`, ref, subdir: parts.slice(4).join('/') || undefined, raw };
+    }
+    const owner = parts[0];
+    const repoName = parts[1];
+    if (!/^[\w.-]+$/.test(owner) || !/^[\w.-]+$/.test(repoName)) {
+        throw new Error(`Invalid GitHub owner/repo in "${spec}".`);
+    }
+    return {
+        kind: 'github',
+        repo: `${owner}/${repoName}`,
+        ref,
+        subdir: parts.slice(2).join('/') || undefined,
+        raw,
+    };
+}
+// ─── Inspection (safety surface) ──────────────────────────────────────────────
+function listMd(dir) {
+    try {
+        return fs.readdirSync(dir).filter((f) => f.endsWith('.md')).map((f) => f.replace(/\.md$/, ''));
+    }
+    catch {
+        return [];
+    }
+}
+/** What does this plugin contain? Callers must warn on hasHooks/hasMcp. */
+function inspectPluginDir(dir) {
+    let meta = {};
+    try {
+        const j = JSON.parse(fs.readFileSync(path.join(dir, 'plugin.json'), 'utf-8'));
+        meta = {
+            name: typeof j.name === 'string' ? j.name : undefined,
+            version: typeof j.version === 'string' ? j.version : undefined,
+            description: typeof j.description === 'string' ? j.description : undefined,
+        };
+    }
+    catch { /* optional */ }
+    return {
+        commands: listMd(path.join(dir, 'commands')),
+        agents: listMd(path.join(dir, 'agents')),
+        hasHooks: fs.existsSync(path.join(dir, 'hooks.json')),
+        hasMcp: fs.existsSync(path.join(dir, 'mcp.json')),
+        meta,
+    };
+}
+/** Is this directory a plausible plugin root? */
+function looksLikePlugin(dir) {
+    const i = inspectPluginDir(dir);
+    return i.commands.length > 0 || i.agents.length > 0 || i.hasHooks || i.hasMcp || i.meta.name !== undefined;
+}
+// ─── Download & extract ───────────────────────────────────────────────────────
+async function downloadTarball(repo, ref, destFile) {
+    const r = ref || 'HEAD';
+    const url = `https://codeload.github.com/${repo}/tar.gz/${encodeURIComponent(r)}`;
+    const res = await fetch(url, { redirect: 'follow' });
+    if (!res.ok) {
+        if (res.status === 404) {
+            throw new Error(`GitHub repo or ref not found: ${repo}${ref ? `#${ref}` : ''} (is the repo public?)`);
+        }
+        throw new Error(`Download failed (${res.status}) for ${repo}${ref ? `#${ref}` : ''}.`);
+    }
+    const buf = Buffer.from(await res.arrayBuffer());
+    if (buf.length > 50 * 1024 * 1024)
+        throw new Error('Plugin tarball exceeds 50 MB — refusing to install.');
+    fs.writeFileSync(destFile, buf);
+}
+function extractTarball(tarFile, destDir) {
+    fs.mkdirSync(destDir, { recursive: true });
+    (0, child_process_1.execFileSync)('tar', ['-xzf', tarFile, '-C', destDir], { stdio: 'pipe' });
+    // Tarball contains a single top-level dir: <repo>-<sha>/
+    const entries = fs.readdirSync(destDir).filter((e) => {
+        try {
+            return fs.statSync(path.join(destDir, e)).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    });
+    if (entries.length !== 1)
+        throw new Error('Unexpected tarball layout.');
+    return path.join(destDir, entries[0]);
+}
+// ─── Copy (sanitised) ─────────────────────────────────────────────────────────
+/** Recursively copy a plugin dir, skipping VCS/junk and anything huge. */
+function copyPluginDir(src, dest) {
+    const SKIP = new Set(['.git', 'node_modules', '.github', '.DS_Store', RECEIPT_FILE]);
+    fs.mkdirSync(dest, { recursive: true });
+    for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+        if (SKIP.has(entry.name))
+            continue;
+        const s = path.join(src, entry.name);
+        const d = path.join(dest, entry.name);
+        if (entry.isSymbolicLink())
+            continue; // never follow symlinks out of the tree
+        if (entry.isDirectory()) {
+            copyPluginDir(s, d);
+        }
+        else if (entry.isFile()) {
+            fs.copyFileSync(s, d);
+        }
+    }
+}
+function pluginsRoot(scope, workDir) {
+    return scope === 'project'
+        ? path.join(workDir || process.cwd(), '.nexrall', 'plugins')
+        : path.join(os.homedir(), '.nexrall', 'plugins');
+}
+async function installPlugin(spec, opts = {}) {
+    const source = parsePluginSource(spec);
+    const scope = opts.scope ?? 'global';
+    const tmpBase = fs.mkdtempSync(path.join(os.tmpdir(), 'nexrall-plugin-'));
+    try {
+        // 1. Materialise the source into tmp
+        let repoRoot;
+        if (source.kind === 'local') {
+            if (!fs.existsSync(source.repo) || !fs.statSync(source.repo).isDirectory()) {
+                throw new Error(`Local plugin path not found: ${source.repo}`);
+            }
+            repoRoot = source.repo;
+        }
+        else {
+            const tarFile = path.join(tmpBase, 'plugin.tar.gz');
+            await downloadTarball(source.repo, source.ref, tarFile);
+            repoRoot = extractTarball(tarFile, path.join(tmpBase, 'x'));
+        }
+        // 2. Locate the plugin root
+        let pluginRoot = source.subdir ? path.join(repoRoot, source.subdir) : repoRoot;
+        pluginRoot = path.resolve(pluginRoot);
+        if (!path.resolve(pluginRoot).startsWith(path.resolve(repoRoot))) {
+            throw new Error('Plugin subdirectory escapes the repository — refusing.');
+        }
+        if (!fs.existsSync(pluginRoot) || !fs.statSync(pluginRoot).isDirectory()) {
+            throw new Error(`Subdirectory not found in repo: ${source.subdir}`);
+        }
+        if (!looksLikePlugin(pluginRoot)) {
+            // Convention fallback: a repo may keep the plugin in ./plugin or ./.nexrall-plugin
+            const candidates = ['plugin', '.nexrall-plugin'].map((c) => path.join(pluginRoot, c));
+            const found = candidates.find((c) => fs.existsSync(c) && looksLikePlugin(c));
+            if (found) {
+                pluginRoot = found;
+            }
+            else {
+                throw new Error('No plugin found: expected plugin.json, commands/, agents/, hooks.json or mcp.json at the source root.');
+            }
+        }
+        // 3. Inspect + name
+        const inspection = inspectPluginDir(pluginRoot);
+        const name = opts.name ||
+            inspection.meta.name ||
+            (source.subdir ? path.basename(source.subdir) : undefined) ||
+            (source.kind === 'github' ? source.repo.split('/')[1] : path.basename(source.repo));
+        if (!/^[\w.-]+$/.test(name))
+            throw new Error(`Invalid plugin name "${name}".`);
+        // 4. Caller confirmation (safety gate — hooks/MCP warnings live here)
+        if (opts.confirm) {
+            const ok = await opts.confirm(inspection, name);
+            if (!ok)
+                throw new Error('Installation cancelled.');
+        }
+        // 5. Copy into place
+        const root = pluginsRoot(scope, opts.workDir);
+        const dest = path.join(root, name);
+        if (fs.existsSync(dest)) {
+            if (!opts.force)
+                throw new Error(`Plugin "${name}" is already installed. Use --force to overwrite or 'nex plugin update ${name}'.`);
+            fs.rmSync(dest, { recursive: true, force: true });
+        }
+        copyPluginDir(pluginRoot, dest);
+        // 6. Receipt for `nex plugin update`
+        const receipt = {
+            source: source.raw,
+            kind: source.kind,
+            ref: source.ref,
+            subdir: source.subdir,
+            installedAt: new Date().toISOString(),
+        };
+        fs.writeFileSync(path.join(dest, RECEIPT_FILE), JSON.stringify(receipt, null, 2));
+        return { name, dir: dest, scope, inspection };
+    }
+    finally {
+        fs.rmSync(tmpBase, { recursive: true, force: true });
+    }
+}
+function readReceipt(pluginDir) {
+    try {
+        const j = JSON.parse(fs.readFileSync(path.join(pluginDir, RECEIPT_FILE), 'utf-8'));
+        return typeof j.source === 'string' ? j : null;
+    }
+    catch {
+        return null;
+    }
+}
+function removePlugin(name, opts = {}) {
+    if (!/^[\w.-]+$/.test(name))
+        throw new Error(`Invalid plugin name "${name}".`);
+    // Search both scopes when none specified (project first — mirrors loader precedence)
+    const scopes = opts.scope ? [opts.scope] : ['project', 'global'];
+    for (const s of scopes) {
+        const dir = path.join(pluginsRoot(s, opts.workDir), name);
+        if (fs.existsSync(dir)) {
+            fs.rmSync(dir, { recursive: true, force: true });
+            return dir;
+        }
+    }
+    throw new Error(`Plugin "${name}" is not installed.`);
+}
+async function updatePlugin(name, opts = {}) {
+    const scopes = opts.scope ? [opts.scope] : ['project', 'global'];
+    for (const s of scopes) {
+        const dir = path.join(pluginsRoot(s, opts.workDir), name);
+        if (!fs.existsSync(dir))
+            continue;
+        const receipt = readReceipt(dir);
+        if (!receipt) {
+            throw new Error(`Plugin "${name}" has no install receipt (installed manually?) — reinstall it with 'nex plugin install <source> --force'.`);
+        }
+        if (receipt.kind === 'local') {
+            throw new Error(`Plugin "${name}" was installed from a local path — re-run 'nex plugin install ${receipt.source} --force'.`);
+        }
+        return installPlugin(receipt.source, { scope: s, workDir: opts.workDir, name, force: true, confirm: opts.confirm });
+    }
+    throw new Error(`Plugin "${name}" is not installed.`);
+}
+//# sourceMappingURL=installer.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nexrall/code-core",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Core agent loop, tools, and extension primitives for Nexrall Code — embed an AI coding agent in any Node.js application.",
   "license": "MIT",
   "author": "Nexrall <support@nexrall.com> (https://nexrall.com)",