qiongli 0.9.0-beta.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jiaxin Peng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,20 @@
+# qiongli
+
+`qiongli` is the npm/npx installer for the Qiongli academic workflow skills.
+
+## Install
+
+```bash
+npm install -g qiongli
+qiongli install --target all
+```
+
+Or run without a global install:
+
+```bash
+npx qiongli@next install --target all
+```
+
+The npm package contains the complete `qiongli-workflow` skill payload and does not depend on PyPI for skill installation.
+
+Advanced bridge commands such as `doctor`, `task-run`, and `team-run` use the Python runtime bundled in the npm package and require Python 3.12+ with `PyYAML`.

package/bin/qiongli.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from '../lib/cli.mjs';
+
+process.exitCode = await main(process.argv.slice(2));

package/lib/args.mjs

@@ -0,0 +1,67 @@
+const TARGETS = new Set(['codex', 'claude', 'gemini', 'antigravity', 'all']);
+const MODES = new Set(['copy', 'link']);
+const BRIDGE_COMMANDS = new Set(['doctor', 'task-run', 'team-run', 'parallel', 'chain', 'role', 'single', 'code-build', 'task-plan']);
+
+export function parseArgv(argv) {
+  const [rawCommand = 'help', ...restArgs] = argv;
+  if (BRIDGE_COMMANDS.has(rawCommand)) {
+    return { command: rawCommand, options: {}, rest: restArgs };
+  }
+
+  const command = rawCommand === 'upgrade' ? 'install' : rawCommand;
+  const options = {
+    target: 'all',
+    mode: 'copy',
+    projectDir: '.',
+    overwrite: rawCommand === 'upgrade',
+    dryRun: false,
+    json: false,
+    globals: false,
+  };
+  const rest = [];
+
+  for (let i = 0; i < restArgs.length; i += 1) {
+    const arg = restArgs[i];
+    if (arg === '--target') {
+      options.target = requireValue(restArgs, i, arg);
+      i += 1;
+    } else if (arg === '--mode') {
+      options.mode = requireValue(restArgs, i, arg);
+      i += 1;
+    } else if (arg === '--project-dir') {
+      options.projectDir = requireValue(restArgs, i, arg);
+      i += 1;
+    } else if (arg === '--cwd') {
+      options.cwd = requireValue(restArgs, i, arg);
+      i += 1;
+    } else if (arg === '--overwrite') {
+      options.overwrite = true;
+    } else if (arg === '--dry-run') {
+      options.dryRun = true;
+    } else if (arg === '--json') {
+      options.json = true;
+    } else if (arg === '--globals') {
+      options.globals = true;
+    } else if (arg === '-h' || arg === '--help') {
+      options.help = true;
+    } else {
+      rest.push(arg);
+    }
+  }
+
+  if (options.target && !TARGETS.has(options.target)) {
+    throw new Error(`Unsupported target: ${options.target}`);
+  }
+  if (options.mode && !MODES.has(options.mode)) {
+    throw new Error(`Unsupported mode: ${options.mode}`);
+  }
+  return { command, options, rest };
+}
+
+function requireValue(args, index, flag) {
+  const value = args[index + 1];
+  if (!value || value.startsWith('--')) {
+    throw new Error(`Missing value for ${flag}`);
+  }
+  return value;
+}

package/lib/cli.mjs

@@ -0,0 +1,112 @@
+import { parseArgv } from './args.mjs';
+import { packageRoot } from './package-root.mjs';
+import { buildCheck, cleanAssets, installSkills } from './installer.mjs';
+import { checkPythonRuntime, runBridgeCommand } from './python-runtime.mjs';
+
+const BRIDGE_COMMANDS = new Set(['doctor', 'task-run', 'team-run', 'parallel', 'chain', 'role', 'single', 'code-build', 'task-plan']);
+
+export async function main(argv, { stdout = process.stdout, stderr = process.stderr } = {}) {
+  const root = packageRoot();
+  let parsed;
+  try {
+    parsed = parseArgv(argv);
+  } catch (error) {
+    stderr.write(`[qiongli] ${error.message}\n`);
+    return 2;
+  }
+
+  if (parsed.options.help || parsed.command === 'help') {
+    stdout.write(helpText());
+    return 0;
+  }
+
+  if (parsed.command === 'install') {
+    const result = installSkills({
+      packageRoot: root,
+      target: parsed.options.target,
+      mode: parsed.options.mode,
+      overwrite: parsed.options.overwrite,
+      dryRun: parsed.options.dryRun,
+    });
+    printInstallResult(result, stdout);
+    return 0;
+  }
+
+  if (parsed.command === 'check') {
+    const payload = { ...buildCheck({ packageRoot: root }), python_bridge: checkPythonRuntime() };
+    if (parsed.options.json) {
+      stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    } else {
+      stdout.write(`Qiongli npm package: ${payload.npm_package.version}\n`);
+      stdout.write(`Payload version: ${payload.payload.version || '<unknown>'}\n`);
+      stdout.write(`Python bridge: ${payload.python_bridge.ok ? 'ok' : 'warn'} - ${payload.python_bridge.message}\n`);
+    }
+    return 0;
+  }
+
+  if (parsed.command === 'clean') {
+    const result = cleanAssets({
+      projectDir: parsed.options.projectDir,
+      globals: parsed.options.globals,
+      dryRun: parsed.options.dryRun,
+    });
+    stdout.write(`[qiongli] removed ${result.removed.length} stale asset(s)\n`);
+    return 0;
+  }
+
+  if (parsed.command === 'runtime') {
+    if (parsed.rest[0] !== 'doctor') {
+      stderr.write('[qiongli] runtime supports only: doctor\n');
+      return 2;
+    }
+    const result = checkPythonRuntime();
+    stdout.write(`${result.ok ? '[ok]' : '[warn]'} ${result.message}\n`);
+    if (result.hint) {
+      stdout.write(`Hint: ${result.hint}\n`);
+    }
+    return result.ok ? 0 : 1;
+  }
+
+  if (BRIDGE_COMMANDS.has(parsed.command)) {
+    const args = parsed.command === 'doctor' && !parsed.rest.includes('--cwd')
+      ? ['--cwd', parsed.options.cwd || '.', ...parsed.rest]
+      : parsed.rest;
+    return runBridgeCommand({ packageRoot: root, command: parsed.command, args });
+  }
+
+  stderr.write(`[qiongli] unknown command: ${parsed.command}\n`);
+  return 2;
+}
+
+function printInstallResult(result, stdout) {
+  stdout.write('Qiongli npm installer\n');
+  stdout.write(`source version: ${result.sourceVersion || '<unknown>'}\n`);
+  for (const residue of result.legacyResidues) {
+    stdout.write(`[legacy] ${residue.target}: ${residue.legacyName} -> ${residue.path}\n`);
+  }
+  for (const action of result.actions) {
+    stdout.write(`[${action.status}] ${action.label} -> ${action.path} (${action.detail})\n`);
+  }
+  stdout.write('Restart Codex / Claude Code / Gemini CLI to activate changes.\n');
+}
+
+function helpText() {
+  return `Qiongli npm installer
+
+Usage:
+  qiongli install --target all
+  qiongli upgrade --target all
+  qiongli check [--json]
+  qiongli clean --project-dir . [--globals]
+  qiongli runtime doctor
+  qiongli doctor --cwd .
+  qiongli task-run ...
+  qiongli team-run ...
+
+Options:
+  --target codex|claude|gemini|antigravity|all
+  --mode copy|link
+  --overwrite
+  --dry-run
+`;
+}

package/lib/installer.mjs

@@ -0,0 +1,228 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const TARGETS = ['codex', 'claude', 'gemini', 'antigravity'];
+const LEGACY_SKILL_NAME = 'research-paper-workflow';
+
+export function resolveTargetPaths({ env = process.env } = {}) {
+  const home = env.HOME || env.USERPROFILE || os.homedir();
+  const codexHome = env.CODEX_HOME || path.join(home, '.codex');
+  const claudeHome = env.CLAUDE_CODE_HOME || path.join(home, '.claude');
+  const geminiHome = env.GEMINI_HOME || path.join(home, '.gemini');
+  const antigravityHome = env.ANTIGRAVITY_HOME || path.join(home, '.gemini', 'antigravity');
+  return {
+    codex: path.join(codexHome, 'skills', 'qiongli-workflow'),
+    claude: path.join(claudeHome, 'skills', 'qiongli-workflow'),
+    gemini: path.join(geminiHome, 'skills', 'qiongli-workflow'),
+    antigravity: path.join(antigravityHome, 'skills', 'qiongli-workflow'),
+  };
+}
+
+export function readSkillVersion(skillDir) {
+  if (!isQiongliSkillDir(skillDir)) {
+    return '';
+  }
+  try {
+    return fs.readFileSync(path.join(skillDir, 'VERSION'), 'utf-8').trim();
+  } catch {
+    return '';
+  }
+}
+
+export function installSkills({
+  packageRoot,
+  target = 'all',
+  mode = 'copy',
+  overwrite = false,
+  dryRun = false,
+  env = process.env,
+  platform = process.platform,
+} = {}) {
+  const workflowSrc = path.join(packageRoot, 'payload', 'qiongli-workflow');
+  if (!fs.existsSync(path.join(workflowSrc, 'SKILL.md'))) {
+    throw new Error(`Missing qiongli-workflow payload: ${workflowSrc}`);
+  }
+
+  const targetPaths = resolveTargetPaths({ env });
+  const selectedTargets = target === 'all' ? TARGETS : [target];
+  const sourceVersion = readSkillVersion(workflowSrc);
+  const actions = [];
+  const legacyResidues = [];
+
+  for (const item of selectedTargets) {
+    const dest = targetPaths[item];
+    const legacyPath = path.join(path.dirname(dest), LEGACY_SKILL_NAME);
+    if (fs.existsSync(legacyPath)) {
+      legacyResidues.push({ target: item, legacyName: LEGACY_SKILL_NAME, path: legacyPath });
+    }
+
+    actions.push(copySkill({ src: workflowSrc, dest, mode, overwrite, dryRun, sourceVersion }));
+
+    if ((item === 'claude' || item === 'gemini') && actions.at(-1).status !== 'skip') {
+      actions.push(...installWorkflowDiscovery({ target: item, skillDest: dest, dryRun, platform }));
+    }
+  }
+
+  return { sourceVersion, actions, legacyResidues, targetPaths };
+}
+
+export function cleanAssets({ projectDir = '.', globals = false, dryRun = false, env = process.env } = {}) {
+  const removed = [];
+  const projectRoot = path.resolve(projectDir);
+  const projectPatterns = [
+    ['.agent', 'workflows'],
+    ['.agent', 'skills', 'qiongli-workflow'],
+    ['.agent', 'skills', LEGACY_SKILL_NAME],
+    ['.agents', 'skills', 'qiongli-workflow'],
+    ['.agents', 'skills', LEGACY_SKILL_NAME],
+    ['.gemini', 'qiongli.md'],
+    ['.gemini', 'agent-profiles.example.json'],
+    ['CLAUDE.qiongli.md'],
+  ];
+
+  for (const parts of projectPatterns) {
+    const candidate = path.join(projectRoot, ...parts);
+    if (!fs.existsSync(candidate)) {
+      continue;
+    }
+    removePath(candidate, dryRun);
+    removed.push(candidate);
+  }
+
+  if (globals) {
+    const targetPaths = resolveTargetPaths({ env });
+    for (const [target, skillDest] of Object.entries(targetPaths)) {
+      if (target !== 'claude' && target !== 'gemini') {
+        continue;
+      }
+      const discoveryDir = discoveryDirectory(target, skillDest);
+      if (!fs.existsSync(discoveryDir)) {
+        continue;
+      }
+      for (const name of fs.readdirSync(discoveryDir)) {
+        const item = path.join(discoveryDir, name);
+        if (isManagedDiscoveryFile(item)) {
+          removePath(item, dryRun);
+          removed.push(item);
+        }
+      }
+    }
+  }
+
+  return { removed };
+}
+
+export function buildCheck({ packageRoot, env = process.env } = {}) {
+  const packageJson = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf-8'));
+  const payload = path.join(packageRoot, 'payload', 'qiongli-workflow');
+  const targetPaths = resolveTargetPaths({ env });
+  const installed = {};
+  for (const [target, skillDir] of Object.entries(targetPaths)) {
+    installed[target] = {
+      path: skillDir,
+      installed: isQiongliSkillDir(skillDir),
+      version: readSkillVersion(skillDir) || null,
+    };
+  }
+  return {
+    npm_package: {
+      name: packageJson.name,
+      version: packageJson.version,
+    },
+    payload: {
+      path: payload,
+      version: readSkillVersion(payload),
+    },
+    installed,
+  };
+}
+
+function copySkill({ src, dest, mode, overwrite, dryRun, sourceVersion }) {
+  if (fs.existsSync(dest)) {
+    if (!overwrite) {
+      if (isQiongliSkillDir(dest)) {
+        const destVersion = readSkillVersion(dest);
+        if (destVersion === sourceVersion) {
+          return { label: 'Skill', status: 'skip', path: dest, detail: `already current ${sourceVersion}` };
+        }
+      } else {
+        return { label: 'Skill', status: 'skip', path: dest, detail: 'use --overwrite for unmanaged directory' };
+      }
+    }
+    removePath(dest, dryRun);
+  }
+
+  if (!dryRun) {
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    if (mode === 'link') {
+      fs.symlinkSync(src, dest, process.platform === 'win32' ? 'junction' : 'dir');
+    } else {
+      fs.cpSync(src, dest, { recursive: true, force: true });
+    }
+  }
+
+  return { label: 'Skill', status: 'ok', path: dest, detail: `installed ${sourceVersion}` };
+}
+
+function installWorkflowDiscovery({ target, skillDest, dryRun, platform }) {
+  const workflowsDir = path.join(skillDest, 'workflows');
+  if (!fs.existsSync(workflowsDir)) {
+    return [];
+  }
+  const actions = [];
+  const discoveryDir = discoveryDirectory(target, skillDest);
+  if (!dryRun) {
+    fs.mkdirSync(discoveryDir, { recursive: true });
+  }
+
+  for (const file of fs.readdirSync(workflowsDir).filter((name) => name.endsWith('.md'))) {
+    const src = path.join(workflowsDir, file);
+    const dest = path.join(discoveryDir, file);
+    if (!dryRun && fs.existsSync(dest)) {
+      fs.rmSync(dest, { force: true, recursive: true });
+    }
+    if (!dryRun) {
+      if (platform === 'win32') {
+        fs.copyFileSync(src, dest);
+      } else {
+        fs.symlinkSync(src, dest);
+      }
+    }
+    actions.push({ label: 'Workflow', status: 'ok', path: dest, detail: platform === 'win32' ? 'copied' : 'linked' });
+  }
+  return actions;
+}
+
+function discoveryDirectory(target, skillDest) {
+  const clientHome = path.dirname(path.dirname(skillDest));
+  return path.join(clientHome, target === 'claude' ? 'commands' : 'workflows');
+}
+
+function isQiongliSkillDir(skillDir) {
+  try {
+    return fs.readFileSync(path.join(skillDir, 'SKILL.md'), 'utf-8').includes('name: qiongli-workflow');
+  } catch {
+    return false;
+  }
+}
+
+function isManagedDiscoveryFile(item) {
+  try {
+    if (fs.lstatSync(item).isSymbolicLink()) {
+      const target = fs.realpathSync(item);
+      return target.includes('qiongli-workflow') || target.includes(LEGACY_SKILL_NAME);
+    }
+    const content = fs.readFileSync(item, 'utf-8');
+    return content.includes('qiongli-workflow') || content.includes('Qiongli');
+  } catch {
+    return false;
+  }
+}
+
+function removePath(target, dryRun) {
+  if (dryRun) {
+    return;
+  }
+  fs.rmSync(target, { recursive: true, force: true });
+}

package/lib/package-root.mjs

@@ -0,0 +1,6 @@
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+export function packageRoot() {
+  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+}

package/lib/python-runtime.mjs

@@ -0,0 +1,77 @@
+import { spawnSync as nodeSpawnSync } from 'node:child_process';
+import path from 'node:path';
+
+export function checkPythonRuntime({
+  candidates = ['python3', 'python'],
+  spawnSync = nodeSpawnSync,
+} = {}) {
+  for (const candidate of candidates) {
+    const version = spawnSync(candidate, [
+      '-c',
+      'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}")',
+    ], { encoding: 'utf-8' });
+    if (version.status !== 0) {
+      continue;
+    }
+
+    const rawVersion = String(version.stdout || '').trim();
+    const [major, minor] = rawVersion.split('.').map((item) => Number.parseInt(item, 10));
+    if (major < 3 || (major === 3 && minor < 12)) {
+      return {
+        ok: false,
+        python: candidate,
+        version: rawVersion,
+        message: `Python bridge requires Python 3.12+, found ${rawVersion}.`,
+        hint: 'Install Python 3.12+ or use `pipx install qiongli`.',
+      };
+    }
+
+    const yaml = spawnSync(candidate, ['-c', 'import yaml'], { encoding: 'utf-8' });
+    if (yaml.status !== 0) {
+      return {
+        ok: false,
+        python: candidate,
+        version: rawVersion,
+        message: 'Python bridge requires PyYAML.',
+        hint: `${candidate} -m pip install PyYAML, or use \`pipx install qiongli\`.`,
+      };
+    }
+
+    return {
+      ok: true,
+      python: candidate,
+      version: rawVersion,
+      message: `Python bridge ready (${candidate} ${rawVersion}).`,
+      hint: '',
+    };
+  }
+
+  return {
+    ok: false,
+    python: '',
+    version: '',
+    message: 'Python runtime not found.',
+    hint: 'Install Python 3.12+ and PyYAML, or use `pipx install qiongli`.',
+  };
+}
+
+export function runBridgeCommand({ packageRoot, command, args, cwd = process.cwd(), env = process.env, stdio = 'inherit' }) {
+  const runtime = checkPythonRuntime();
+  if (!runtime.ok) {
+    console.error(`[qiongli] ${runtime.message}`);
+    console.error(`Hint: ${runtime.hint}`);
+    return 1;
+  }
+
+  const pythonPath = path.join(packageRoot, 'python-runtime');
+  const childEnv = {
+    ...env,
+    PYTHONPATH: env.PYTHONPATH ? `${pythonPath}${path.delimiter}${env.PYTHONPATH}` : pythonPath,
+  };
+  const result = nodeSpawnSync(runtime.python, ['-m', 'bridges.orchestrator', command, ...args], {
+    cwd,
+    env: childEnv,
+    stdio,
+  });
+  return typeof result.status === 'number' ? result.status : 1;
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "qiongli",
+  "version": "0.9.0-beta.4",
+  "description": "npm/npx installer and optional Python bridge runtime for Qiongli academic workflow skills.",
+  "type": "module",
+  "bin": {
+    "qiongli": "bin/qiongli.mjs"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "payload/",
+    "python-runtime/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/jxpeng98/qiongli",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jxpeng98/qiongli.git",
+    "directory": "packages/npm-qiongli"
+  },
+  "bugs": {
+    "url": "https://github.com/jxpeng98/qiongli/issues"
+  }
+}