@quicktvui/ai-cli 0.1.3 → 1.1.1

package/README.md

@@ -41,6 +41,8 @@ quicktvui-aicreate-project quick-tv-app
 - `--skip-install`: skip dependency install for `create-project`
 - `--strict`: fail on doctor check issues
 - `--lang <code>`: prompt language for `prompt` command (`zh` or `en`)
+- `--gemini-dir <path>`: custom Gemini config directory (default `~/.gemini`, or `$GEMINI_CLI_HOME/.gemini`)
+- `--skip-gemini-config`: skip updating Gemini bridge config during `init`/`update`
 - `--node-major <n>`: target Node.js LTS major for `setup-vue-env` (default `20`)
 - `--skip-node-install`: skip Node.js install stage in `setup-vue-env`
 - `--force-node-install`: force Node.js install stage in `setup-vue-env`
@@ -76,6 +78,12 @@ quicktvui-ai doctor
 
 Then reload your AI agent so it rescans local skills.
 
+`init`/`update` also auto-maintains Gemini global context files:
+
+- updates `~/.gemini/GEMINI.md` with QuickTVUI `@.../SKILL.md` bridge block
+- ensures `~/.gemini/settings.json` contains `context.fileName` entries:
+  `GEMINI.md`, `AGENTS.md`, `SKILL.md`, `CONTEXT.md`
+
 ## Create project with network fallback
 
 ```bash

package/lib/index.js

@@ -7,7 +7,7 @@ const https = require("https");
 const net = require("net");
 const { spawnSync, spawn } = require("child_process");
 
-const PACKAGE_VERSION = "0.1.2";
+const PACKAGE_VERSION = "0.1.4";
 const DEFAULT_INSTALL_DIR = path.join(
   os.homedir(),
   ".agents",
@@ -36,6 +36,14 @@ const REQUIRED_SKILL_FILES = [
   path.join("references", "lookup-checklist.md"),
   path.join("references", "bug-report-template.md"),
 ];
+const QUICKTVUI_GEMINI_BRIDGE_START = "<!-- QUICKTVUI_SKILL_BRIDGE_START -->";
+const QUICKTVUI_GEMINI_BRIDGE_END = "<!-- QUICKTVUI_SKILL_BRIDGE_END -->";
+const DEFAULT_GEMINI_CONTEXT_FILENAMES = [
+  "GEMINI.md",
+  "AGENTS.md",
+  "SKILL.md",
+  "CONTEXT.md",
+];
 
 function exists(filePath) {
   return fs.existsSync(filePath);
@@ -65,6 +73,21 @@ function removeDirectoryIfExists(dirPath) {
   }
 }
 
+function backupFile(filePath) {
+  if (!exists(filePath)) return null;
+  const backupPath = `${filePath}.bak`;
+  try {
+    fs.copyFileSync(filePath, backupPath);
+    return backupPath;
+  } catch (error) {
+    return null;
+  }
+}
+
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
 function needsWindowsShell(command) {
   return process.platform === "win32" && /\.(bat|cmd)$/i.test(String(command));
 }
@@ -2288,6 +2311,8 @@ Options:
   --skip-install    Skip dependency install in create-project
   --strict          Non-zero exit in doctor when checks fail
   --lang <code>     Prompt language for 'prompt' command: zh | en
+  --gemini-dir <path> Gemini config directory (default: ~/.gemini or $GEMINI_CLI_HOME/.gemini)
+  --skip-gemini-config Skip updating Gemini bridge files during init/update
   --yes             Non-interactive mode; accept default prompts
   --no-interactive  Disable interactive prompts
   --node-major <n>  Target Node.js LTS major for setup-vue-env (default: 20)
@@ -2401,6 +2426,191 @@ function installSkills(installDir) {
   return { installDir, sourceDir };
 }
 
+function resolveGeminiConfigDir(args) {
+  if (typeof args["gemini-dir"] === "string" && args["gemini-dir"].trim()) {
+    return path.resolve(args["gemini-dir"].trim());
+  }
+
+  const customGeminiHome = process.env.GEMINI_CLI_HOME
+    ? String(process.env.GEMINI_CLI_HOME).trim()
+    : "";
+  if (customGeminiHome) {
+    const resolved = path.resolve(customGeminiHome);
+    if (path.basename(resolved).toLowerCase() === ".gemini") {
+      return resolved;
+    }
+    return path.join(resolved, ".gemini");
+  }
+
+  return path.join(os.homedir(), ".gemini");
+}
+
+function buildGeminiBridgeImportPaths(installDir) {
+  const preferredFiles = [
+    "SKILL.md",
+    path.join("references", "create-project-checklist.md"),
+    path.join("references", "dev-env-checklist.md"),
+    path.join("references", "esapp-protocol-cheatsheet.md"),
+  ];
+
+  const importPaths = [];
+  for (const relPath of preferredFiles) {
+    const absolutePath = path.join(installDir, relPath);
+    if (exists(absolutePath)) {
+      importPaths.push(absolutePath);
+    }
+  }
+
+  if (importPaths.length === 0) {
+    importPaths.push(path.join(installDir, "SKILL.md"));
+  }
+
+  return importPaths;
+}
+
+function updateGeminiBridgeConfig(args, installDir) {
+  if (toBooleanFlag(args["skip-gemini-config"], false)) {
+    return {
+      skipped: true,
+      reason: "flag",
+    };
+  }
+
+  const geminiDir = resolveGeminiConfigDir(args);
+  ensureDir(geminiDir);
+
+  const geminiMdPath = path.join(geminiDir, "GEMINI.md");
+  const settingsPath = path.join(geminiDir, "settings.json");
+  const importPaths = buildGeminiBridgeImportPaths(installDir);
+
+  const bridgeBlock = [
+    QUICKTVUI_GEMINI_BRIDGE_START,
+    "QuickTVUI global skill bridge (managed by quicktvui-ai assistant).",
+    ...importPaths.map((importPath) => `@${importPath}`),
+    QUICKTVUI_GEMINI_BRIDGE_END,
+  ].join("\n");
+
+  const beforeGeminiMd = exists(geminiMdPath)
+    ? fs.readFileSync(geminiMdPath, "utf8")
+    : "";
+  const bridgePattern = new RegExp(
+    `${escapeRegExp(QUICKTVUI_GEMINI_BRIDGE_START)}[\\s\\S]*?${escapeRegExp(QUICKTVUI_GEMINI_BRIDGE_END)}`,
+    "m",
+  );
+  let nextGeminiMd;
+  if (bridgePattern.test(beforeGeminiMd)) {
+    nextGeminiMd = beforeGeminiMd.replace(bridgePattern, bridgeBlock);
+  } else {
+    const trimmed = beforeGeminiMd.replace(/\s*$/, "");
+    nextGeminiMd = trimmed
+      ? `${trimmed}\n\n${bridgeBlock}\n`
+      : `${bridgeBlock}\n`;
+  }
+
+  let geminiMdUpdated = false;
+  let geminiMdBackup = null;
+  if (nextGeminiMd !== beforeGeminiMd) {
+    geminiMdBackup = backupFile(geminiMdPath);
+    fs.writeFileSync(geminiMdPath, nextGeminiMd, "utf8");
+    geminiMdUpdated = true;
+  }
+
+  const result = {
+    skipped: false,
+    geminiDir,
+    geminiMdPath,
+    settingsPath,
+    importPaths,
+    geminiMdUpdated,
+    geminiMdBackup,
+    settingsUpdated: false,
+    settingsBackup: null,
+    settingsParseError: null,
+  };
+
+  let settings = {};
+  const beforeSettings = exists(settingsPath)
+    ? fs.readFileSync(settingsPath, "utf8")
+    : "";
+  if (beforeSettings.trim()) {
+    try {
+      settings = JSON.parse(beforeSettings);
+    } catch (error) {
+      result.settingsParseError = error.message;
+      return result;
+    }
+  }
+
+  if (!settings || typeof settings !== "object" || Array.isArray(settings)) {
+    settings = {};
+  }
+  if (!settings.context || typeof settings.context !== "object") {
+    settings.context = {};
+  }
+
+  const current = settings.context.fileName;
+  const normalizedList = Array.isArray(current)
+    ? current
+        .map((item) => String(item).trim())
+        .filter((item) => item.length > 0)
+    : typeof current === "string" && current.trim()
+      ? [current.trim()]
+      : [];
+
+  const lowerSet = new Set(normalizedList.map((item) => item.toLowerCase()));
+  for (const fileName of DEFAULT_GEMINI_CONTEXT_FILENAMES) {
+    if (!lowerSet.has(fileName.toLowerCase())) {
+      normalizedList.push(fileName);
+      lowerSet.add(fileName.toLowerCase());
+    }
+  }
+  settings.context.fileName = normalizedList;
+
+  const nextSettings = `${JSON.stringify(settings, null, 2)}\n`;
+  if (nextSettings !== beforeSettings) {
+    result.settingsBackup = backupFile(settingsPath);
+    fs.writeFileSync(settingsPath, nextSettings, "utf8");
+    result.settingsUpdated = true;
+  }
+
+  return result;
+}
+
+function printGeminiBridgeResult(state) {
+  if (!state) return;
+  if (state.error) {
+    console.log(`- Gemini config: failed (${state.error})`);
+    console.log(
+      `  Hint: rerun with --skip-gemini-config or fix filesystem permission.`,
+    );
+    return;
+  }
+  if (state.skipped) {
+    console.log(`- Gemini config: skipped (--skip-gemini-config)`);
+    return;
+  }
+
+  console.log(`- Gemini config dir: ${state.geminiDir}`);
+  console.log(
+    `- Gemini bridge block: ${state.geminiMdUpdated ? "updated" : "already up to date"}`,
+  );
+  console.log(
+    `- Gemini context.fileName: ${
+      state.settingsParseError
+        ? "skipped (settings.json parse failed)"
+        : state.settingsUpdated
+          ? "updated"
+          : "already up to date"
+    }`,
+  );
+  if (state.settingsParseError) {
+    console.log(`  Warning: ${state.settingsParseError}`);
+    console.log(
+      `  Hint: fix ${state.settingsPath} JSON and rerun 'quicktvui-ai init'.`,
+    );
+  }
+}
+
 function printDoctorReport(skillState, projectState, projectRoot) {
   console.log(`Skill dir: ${skillState.installDir}`);
   console.log(`- Directory exists: ${skillState.exists ? "yes" : "no"}`);
@@ -2428,9 +2638,16 @@ function printDoctorReport(skillState, projectState, projectRoot) {
 async function runInit(args) {
   const installDir = getInstallDir(args);
   const result = installSkills(installDir);
+  let geminiState;
+  try {
+    geminiState = updateGeminiBridgeConfig(args, result.installDir);
+  } catch (error) {
+    geminiState = { error: error.message };
+  }
   console.log(`Installed QuickTVUI skill assets.`);
   console.log(`- source: ${result.sourceDir}`);
   console.log(`- target: ${result.installDir}`);
+  printGeminiBridgeResult(geminiState);
   console.log(`Next: restart/reload your AI agent so it can rescan skills.`);
 }
 
@@ -2484,9 +2701,16 @@ async function runValidate(args) {
 async function runUpdate(args) {
   const installDir = getInstallDir(args);
   const result = installSkills(installDir);
+  let geminiState;
+  try {
+    geminiState = updateGeminiBridgeConfig(args, result.installDir);
+  } catch (error) {
+    geminiState = { error: error.message };
+  }
   console.log(`Updated QuickTVUI skill assets.`);
   console.log(`- source: ${result.sourceDir}`);
   console.log(`- target: ${result.installDir}`);
+  printGeminiBridgeResult(geminiState);
 }
 
 function cloneTemplateProject(targetDir) {
@@ -2571,6 +2795,7 @@ npm install @quicktvui/ai --save-dev
 \`\`\`
 
 安装完成后请提醒用户重启或 reload AI Agent，以便重新扫描 ~/.agents/skills/quicktvui。
+并提示：quicktvui-ai init 会自动更新 ~/.gemini/GEMINI.md 与 ~/.gemini/settings.json 的 QuickTVUI bridge 配置。
 
 创建项目时优先使用：
 \`\`\`bash
@@ -2606,6 +2831,7 @@ npm install @quicktvui/ai --save-dev
 \`\`\`
 
 After installation, ask the user to restart or reload the AI Agent so it rescans ~/.agents/skills/quicktvui.
+Also note that quicktvui-ai init auto-updates QuickTVUI bridge config in ~/.gemini/GEMINI.md and ~/.gemini/settings.json.
 
 When creating a project, prefer:
 \`\`\`bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quicktvui/ai-cli",
-  "version": "0.1.3",
+  "version": "1.1.1",
   "description": "CLI for installing and validating QuickTVUI AI skills",
   "bin": {
     "quicktvui-ai": "bin/quicktvui-ai.js",

package/scripts/install

@@ -41,4 +41,5 @@ else
   quicktvui-ai doctor --strict --dir "$INSTALL_DIR"
 fi
 
-echo "Done. Reload your AI agent to rescan local skills."
+echo "Done. quicktvui-ai init also updated Gemini bridge config under ~/.gemini."
+echo "Reload your AI agent to rescan local skills."

package/scripts/install.ps1

@@ -25,4 +25,5 @@ if ($Project -and $Project.Length -gt 0) {
   quicktvui-ai doctor --strict --dir $Dir
 }
 
-Write-Host "Done. Reload your AI agent to rescan local skills." -ForegroundColor Green
+Write-Host "Done. quicktvui-ai init also updated Gemini bridge config under ~/.gemini." -ForegroundColor Green
+Write-Host "Reload your AI agent to rescan local skills." -ForegroundColor Green