@minhpnq1807/contextos 0.5.21 → 0.5.23

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.5.23
+
+- **Fix Windows install paths:** Replaces all `process.env.HOME || process.cwd()` fallbacks with `os.homedir()` across `ctx.js`, `claude-hooks.js`, `antigravity-hooks.js`, `claude-mcp.js`, `antigravity-mcp.js`, and `ruler-sync.js`. On Windows, `HOME` is not set, causing `.codex/`, `.claude/`, and `.gemini/` directories (with full `node_modules` and source code) to be created inside the project tree instead of the user's home directory.
+- **Fix ephemeral MCP server path:** `ctx sync --rules` now resolves the MCP server path from stable install roots (`~/.codex/marketplaces/contextos/`, `~/.ctx/contextos/agents/`) instead of `rootDir`, which may point to a temporary npm extraction directory (e.g. `/tmp/contextos/`) that disappears after cleanup.
+
+## 0.5.22
+
+- Adds `.gitignore` management to `ctx install`: writes inner `.gitignore` (excludes `node_modules/`, `bin/`, `lib/`, `mcp/`) inside installed agent directories and ensures the project root `.gitignore` excludes `.codex/marketplaces/contextos/`, `.claude/settings.json`, and `.gemini/`.
+- Splits the `npm install -g && ctx setup` one-liner into two separate commands in README and LAUNCH docs to avoid shell PATH resolution failures.
+
 ## 0.5.21
 
 - Makes prompt hooks fall back to direct scoring when the `ctx-mcp` bridge socket is missing, stale, or unavailable, avoiding empty `hook context` output.

package/LAUNCH.md

@@ -37,7 +37,8 @@ It supports Codex, Claude Code, and Antigravity. It is local-first and uses loca
 
 Install:
 
-npm install -g @minhpnq1807/contextos && ctx setup
+npm install -g @minhpnq1807/contextos
+ctx setup
 
 Repo: https://github.com/khovan123/contextOS
 ```
@@ -51,7 +52,8 @@ Codex can read AGENTS.md and still ignore the rule that matters.
 
 ContextOS ranks rules per prompt, injects the important ones before work starts, then reports followed / ignored / unknown after the task.
 
-npm install -g @minhpnq1807/contextos && ctx setup
+npm install -g @minhpnq1807/contextos
+ctx setup
 
 https://github.com/khovan123/contextOS
 ```

package/README.md

@@ -49,10 +49,11 @@ Rule outcomes: 8 followed, 0 ignored, 0 unknown
 Runtime telemetry: code-review-graph, code-review-graph.query_graph_tool
 ```
 
-## Install In One Line
+## Quick Install
 
 ```bash
-npm install -g @minhpnq1807/contextos && ctx setup
+npm install -g @minhpnq1807/contextos
+ctx setup
 ```
 
 No postinstall surprise: `npm install` only installs the CLI. Setup runs only when you call `ctx setup`.

package/bin/ctx.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import readline from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
@@ -24,6 +25,7 @@ import { installClaudeMcp } from "../plugins/ctx/lib/claude-mcp.js";
 import { installAntigravityHooks } from "../plugins/ctx/lib/antigravity-hooks.js";
 import { installAntigravityMcp } from "../plugins/ctx/lib/antigravity-mcp.js";
 import { syncRules } from "../plugins/ctx/lib/ruler-sync.js";
+import { writeInnerGitignore, ensureRootGitignore } from "../plugins/ctx/lib/gitignore.js";
 import { syncSkills } from "../plugins/ctx/lib/skillshare-sync.js";
 import { scanSkills, warmSkillEmbeddings } from "../plugins/ctx/lib/skill-discoverer.js";
 import { parsePassthroughArgs, runPassthrough } from "../plugins/ctx/lib/passthrough.js";
@@ -162,7 +164,7 @@ function packageVersion() {
 }
 
 function codexHome() {
-  return process.env.CODEX_HOME || path.join(process.env.HOME || process.cwd(), ".codex");
+  return process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
 }
 
 function copyInstall() {
@@ -194,6 +196,9 @@ async function install({ copy = false, inject = true, agent = "codex" } = {}) {
       const hooksPath = installClaudeHooks({ installRoot, injectPromptContext: inject });
       progress.step(40, "installing mcp");
       const mcpConfigPath = installClaudeMcp({ installRoot });
+      progress.step(50, "configuring gitignore");
+      writeInnerGitignore(installRoot);
+      ensureRootGitignore(process.cwd());
       progress.step(55, "warming embeddings");
       const warmResult = await warmInstallEmbeddings();
       progress.done("claude installed");
@@ -218,6 +223,9 @@ async function install({ copy = false, inject = true, agent = "codex" } = {}) {
       const hooksPath = installAntigravityHooks({ installRoot, injectPromptContext: inject });
       progress.step(40, "installing mcp");
       const mcpConfigPaths = installAntigravityMcp({ installRoot });
+      progress.step(50, "configuring gitignore");
+      writeInnerGitignore(installRoot);
+      ensureRootGitignore(process.cwd());
       progress.step(55, "warming embeddings");
       const warmResult = await warmInstallEmbeddings();
       progress.done("agy installed");
@@ -256,6 +264,10 @@ async function install({ copy = false, inject = true, agent = "codex" } = {}) {
     progress.step(60, "installing hooks");
     const hooksPath = installGlobalHooks({ codexHome: codexHome(), marketplaceRoot, injectPromptContext: inject });
 
+    progress.step(65, "configuring gitignore");
+    writeInnerGitignore(marketplaceRoot);
+    ensureRootGitignore(process.cwd());
+
     progress.step(70, "warming embeddings");
     const warmResult = await warmInstallEmbeddings();
     progress.done("codex installed");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhpnq1807/contextos",
-  "version": "0.5.21",
+  "version": "0.5.23",
   "description": "Task-aware AGENTS.md context injection and compliance reporting for Codex, Claude Code, and Antigravity.",
   "type": "module",
   "bin": {

package/plugins/ctx/lib/antigravity-hooks.js

@@ -1,4 +1,5 @@
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 
 function shellQuote(value) {
@@ -19,7 +20,7 @@ function commandFor(installRoot, scriptName, { injectPromptContext = true } = {}
 
 export function antigravityHooksPath() {
   return process.env.ANTIGRAVITY_HOOKS_PATH
-    || path.join(process.env.HOME || process.cwd(), ".gemini", "config", "hooks.json");
+    || path.join(os.homedir(), ".gemini", "config", "hooks.json");
 }
 
 export function buildAntigravityHooksConfig(existingConfig, { installRoot, injectPromptContext = true } = {}) {

package/plugins/ctx/lib/antigravity-mcp.js

@@ -1,4 +1,5 @@
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 
 function readJsonFile(filePath, fallback) {
@@ -12,7 +13,7 @@ export function antigravityMcpConfigPaths() {
   if (process.env.ANTIGRAVITY_MCP_CONFIG_PATH) {
     return [process.env.ANTIGRAVITY_MCP_CONFIG_PATH];
   }
-  const home = process.env.HOME || process.cwd();
+  const home = os.homedir();
   return [
     path.join(home, ".gemini", "antigravity", "mcp_config.json"),
     path.join(home, ".gemini", "antigravity-cli", "mcp_config.json"),

package/plugins/ctx/lib/claude-hooks.js

@@ -1,4 +1,5 @@
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 
 import { buildGlobalHooksConfig } from "./global-hooks.js";
@@ -11,7 +12,7 @@ function readJsonFile(filePath, fallback) {
 }
 
 export function claudeHome() {
-  return process.env.CLAUDE_HOME || path.join(process.env.HOME || process.cwd(), ".claude");
+  return process.env.CLAUDE_HOME || path.join(os.homedir(), ".claude");
 }
 
 export function installClaudeHooks({ claudeHome: home = claudeHome(), installRoot, injectPromptContext = true } = {}) {

package/plugins/ctx/lib/claude-mcp.js

@@ -1,4 +1,5 @@
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 
 function readJsonFile(filePath, fallback) {
@@ -9,7 +10,7 @@ function readJsonFile(filePath, fallback) {
 }
 
 export function claudeConfigPath() {
-  return process.env.CLAUDE_CONFIG_PATH || path.join(process.env.HOME || process.cwd(), ".claude.json");
+  return process.env.CLAUDE_CONFIG_PATH || path.join(os.homedir(), ".claude.json");
 }
 
 export function buildClaudeMcpConfig(existingConfig, { installRoot } = {}) {

package/plugins/ctx/lib/gitignore.js

@@ -0,0 +1,69 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Entries to exclude inside the installed contextos directory.
+ * Keeps node_modules, bin, lib, and mcp out of version control.
+ */
+const INNER_GITIGNORE_ENTRIES = [
+  "node_modules/",
+  "bin/",
+  "lib/",
+  "mcp/",
+];
+
+/**
+ * Entries that ctx install should add to the project root .gitignore.
+ *
+ * .codex/marketplaces/contextos/ — Codex agent install dir
+ * .claude/settings.json          — Claude hooks written by ctx install
+ * .gemini/                       — Antigravity hooks/config
+ */
+const ROOT_GITIGNORE_ENTRIES = [
+  ".codex/marketplaces/contextos/",
+  ".claude/settings.json",
+  ".gemini/",
+];
+
+/**
+ * Write a .gitignore inside `dir` that excludes build/runtime artefacts.
+ * Creates the directory if it does not exist yet.
+ */
+export function writeInnerGitignore(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+  const gitignorePath = path.join(dir, ".gitignore");
+  const content = INNER_GITIGNORE_ENTRIES.join("\n") + "\n";
+  fs.writeFileSync(gitignorePath, content, "utf8");
+  return gitignorePath;
+}
+
+/**
+ * Ensure the project root .gitignore exists and contains the entries
+ * needed to keep ctx install artefacts out of version control.
+ *
+ * Only appends entries that are not already present.
+ * Creates the file if it does not exist.
+ */
+export function ensureRootGitignore(projectRoot) {
+  const gitignorePath = path.join(projectRoot, ".gitignore");
+  let existing = "";
+  if (fs.existsSync(gitignorePath)) {
+    existing = fs.readFileSync(gitignorePath, "utf8");
+  }
+
+  const lines = existing.split("\n");
+  const missing = ROOT_GITIGNORE_ENTRIES.filter(
+    (entry) => !lines.some((line) => line.trim() === entry)
+  );
+
+  if (missing.length === 0) return gitignorePath;
+
+  const block = [
+    "",
+    "# ContextOS install artefacts",
+    ...missing,
+  ].join("\n") + "\n";
+
+  fs.writeFileSync(gitignorePath, existing.trimEnd() + "\n" + block, "utf8");
+  return gitignorePath;
+}

package/plugins/ctx/lib/ruler-sync.js

@@ -5,9 +5,12 @@ import readline from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
 import { execFileSync } from "node:child_process";
 
+import { defaultDataRoot } from "./workspace-data.js";
+
 const DEFAULT_AGENTS = ["codex", "claude", "antigravity"];
 const CTX_MCP_NAME = "ctx-mcp";
 const CONTEXTOS_PROXY_MARKER = "/contextos/plugins/ctx/mcp/proxy.js";
+const MCP_SERVER_RELATIVE = path.join("plugins", "ctx", "mcp", "server.js");
 const AGENT_ALIASES = new Map([
   ["agy", "antigravity"],
   ["antigravity", "antigravity"],
@@ -54,11 +57,11 @@ function displayAgentName(agent) {
 }
 
 function codexConfigPath() {
-  return path.join(process.env.CODEX_HOME || path.join(process.env.HOME || process.cwd(), ".codex"), "config.toml");
+  return path.join(process.env.CODEX_HOME || path.join(os.homedir(), ".codex"), "config.toml");
 }
 
 function claudeUserConfigPath() {
-  return process.env.CLAUDE_CONFIG_PATH || path.join(process.env.HOME || process.cwd(), ".claude.json");
+  return process.env.CLAUDE_CONFIG_PATH || path.join(os.homedir(), ".claude.json");
 }
 
 export function rulerTomlPath(cwd = process.cwd()) {
@@ -273,7 +276,7 @@ function readRulerMcpServer({ tomlPath, name } = {}) {
 }
 
 function antigravityMcpConfigPaths() {
-  const home = process.env.HOME || process.cwd();
+  const home = os.homedir();
   return [
     path.join(home, ".gemini", "antigravity", "mcp_config.json"),
     path.join(home, ".gemini", "antigravity-cli", "mcp_config.json"),
@@ -456,7 +459,7 @@ export function verifySync({ cwd = process.cwd(), agents = DEFAULT_AGENTS } = {}
   const checks = [];
   const definitions = {
     codex: [path.join(cwd, ".codex", "config.toml")],
-    claude: [path.join(cwd, ".mcp.json"), path.join(cwd, ".claude", "settings.json"), path.join(process.env.HOME || "", ".claude.json")],
+    claude: [path.join(cwd, ".mcp.json"), path.join(cwd, ".claude", "settings.json"), path.join(os.homedir(), ".claude.json")],
     antigravity: [
       path.join(cwd, ".gemini", "settings.json"),
       path.join(cwd, ".gemini", "mcp.json"),
@@ -473,6 +476,21 @@ export function verifySync({ cwd = process.cwd(), agents = DEFAULT_AGENTS } = {}
   return checks;
 }
 
+function resolveStableMcpServerPath(rootDir) {
+  const codexRoot = path.join(process.env.CODEX_HOME || path.join(os.homedir(), ".codex"), "marketplaces", "contextos");
+  const dataRoot = defaultDataRoot();
+  const candidates = [
+    path.join(codexRoot, MCP_SERVER_RELATIVE),
+    path.join(dataRoot, "agents", "claude", "contextos", MCP_SERVER_RELATIVE),
+    path.join(dataRoot, "agents", "agy", "contextos", MCP_SERVER_RELATIVE),
+    path.join(rootDir, MCP_SERVER_RELATIVE)
+  ];
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  return path.join(rootDir, MCP_SERVER_RELATIVE);
+}
+
 export async function syncRules({
   cwd = process.cwd(),
   rootDir,
@@ -495,7 +513,7 @@ export async function syncRules({
   const init = ensureRulerInit({ cwd, run, dryRun: options.dryRun });
   logger(statusLine("Checking .ruler/ruler.toml...", init.created ? "✓ created" : "✓ found"));
 
-  const mcpServerPath = path.join(rootDir, "plugins", "ctx", "mcp", "server.js");
+  const mcpServerPath = resolveStableMcpServerPath(rootDir);
   const injected = injectCtxMcp({
     tomlPath: init.tomlPath,
     mcpServerPath,