@minhpnq1807/contextos 0.5.13 → 0.5.15

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.5.15
+
+- Replaces the misleading `ctx install --agent codex|claude|agy` usage text with separate commands.
+- Adds a clear CLI error when an install agent value contains shell-choice separators such as `|` or `/`.
+
+## 0.5.14
+
+- Adds an actual rendered terminal demo GIF generated from `ctx debug` plus a real `codex exec` hook run.
+- Points the README demo section at `docs/demo/contextos-demo.gif`.
+
 ## 0.5.13
 
 - Reworks the README for launch: demo-first positioning, fear hook, one-line install, before/after, and quick command table.

package/DEMO.md

@@ -2,6 +2,18 @@
 
 Use this to record the README GIF or a short terminal clip.
 
+The current rendered demo is checked in at:
+
+```text
+docs/demo/contextos-demo.gif
+```
+
+It was generated from an actual terminal transcript using:
+
+```text
+node docs/demo/render-terminal-gif.mjs <terminal-log> docs/demo/contextos-demo.gif
+```
+
 ## Goal
 
 Show one thing clearly:

package/README.md

@@ -21,7 +21,7 @@ Published package: [`@minhpnq1807/contextos`](https://www.npmjs.com/package/@min
 
 ## Demo
 
-![ContextOS demo GIF placeholder](docs/contextos-demo-placeholder.svg)
+![ContextOS actual terminal demo](docs/demo/contextos-demo.gif)
 
 Example hook context injected before the agent works:
 
@@ -440,6 +440,8 @@ This warning comes from a transitive dependency in the local embedding/WASM stac
 | `ctx skillshare -- <args>` | Forwards args to the installed `skillshare` CLI. | You need native skillshare commands such as `status`, `target list`, `doctor`, `push`, or `pull`. | Preserves skillshare stdout/stderr and exit status. |
 | `ctx --version` | Prints the installed ContextOS CLI version. | You want to confirm which npm version is being executed. | Prints the version from package metadata. |
 
+Do not run `ctx install --agent codex|claude|agy` in a shell. The `|` character is a pipe, so the shell will run `ctx install --agent codex`, pipe its output into `claude`, then pipe that into `agy`. Pick one command per agent instead.
+
 ## Runtime Files
 
 ContextOS writes shared caches to:

package/bin/ctx.js

@@ -42,7 +42,9 @@ Usage:
   ctx install codex
   ctx install claude
   ctx install agy
-  ctx install --agent codex|claude|agy
+  ctx install --agent codex
+  ctx install --agent claude
+  ctx install --agent agy
   ctx install --quiet
   ctx install --inject
   ctx install --copy
@@ -77,6 +79,17 @@ Usage:
 
 function normalizeInstallAgent(agent) {
   const normalized = String(agent || "").trim().toLowerCase();
+  if (/[|/]/.test(normalized)) {
+    throw new Error([
+      `Invalid agent '${agent}'.`,
+      "Install one agent per command:",
+      "  ctx install --agent codex",
+      "  ctx install --agent claude",
+      "  ctx install --agent agy",
+      "",
+      "Do not run `ctx install --agent codex|claude|agy`: `|` is a shell pipe."
+    ].join("\n"));
+  }
   if (normalized === "antigravity") return "agy";
   return normalized;
 }

package/docs/demo/render-terminal-gif.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+
+const [, , inputPath, outputPath = "docs/demo/contextos-demo.gif"] = process.argv;
+if (!inputPath) {
+  console.error("Usage: node docs/demo/render-terminal-gif.mjs <terminal-log> [output.gif]");
+  process.exit(1);
+}
+
+const width = 960;
+const height = 540;
+const marginX = 52;
+const marginY = 54;
+const lineHeight = 18;
+const maxLines = 22;
+const maxColumns = 100;
+const frameStep = 5;
+
+const raw = fs.readFileSync(inputPath, "utf8");
+const lines = clean(raw)
+  .split(/\r?\n/)
+  .map((line) => line.trimEnd())
+  .filter((line) => line && !line.includes("Script started") && !line.includes("Script done"));
+
+const displayLines = wrapLines(lines, maxColumns).slice(0, 110);
+const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "contextos-demo-frames-"));
+const frames = [];
+
+for (let count = 1; count <= displayLines.length; count += frameStep) {
+  frames.push(writeFrame({ tmpDir, index: frames.length, lines: displayLines.slice(0, count) }));
+}
+frames.push(writeFrame({ tmpDir, index: frames.length, lines: displayLines }));
+
+fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+execFileSync("convert", ["-delay", "12", "-loop", "0", ...frames, outputPath], { stdio: "inherit" });
+console.log(`Wrote ${outputPath}`);
+
+function writeFrame({ tmpDir, index, lines }) {
+  const visible = lines.slice(-maxLines);
+  const svg = [
+    `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}">`,
+    `<rect width="${width}" height="${height}" fill="#0f1419"/>`,
+    `<rect x="24" y="24" width="${width - 48}" height="${height - 48}" rx="16" fill="#151b22" stroke="#34404d"/>`,
+    `<circle cx="56" cy="50" r="6" fill="#ff6b6b"/><circle cx="78" cy="50" r="6" fill="#ffd166"/><circle cx="100" cy="50" r="6" fill="#70d88b"/>`,
+    `<text x="124" y="57" fill="#9aa6b2" font-family="DejaVu Sans Mono, Consolas, monospace" font-size="15">ContextOS actual terminal demo</text>`,
+    `<text x="${marginX}" y="${marginY + 30}" fill="#d8dee9" font-family="DejaVu Sans Mono, Consolas, monospace" font-size="15">`
+  ];
+  visible.forEach((line, offset) => {
+    const y = offset === 0 ? 0 : lineHeight;
+    svg.push(`<tspan x="${marginX}" dy="${y}" fill="${colorForLine(line)}">${escapeXml(line)}</tspan>`);
+  });
+  svg.push("</text></svg>");
+  const filePath = path.join(tmpDir, `frame-${String(index).padStart(4, "0")}.svg`);
+  fs.writeFileSync(filePath, svg.join(""));
+  return filePath;
+}
+
+function clean(value) {
+  return String(value)
+    .replace(/\x1B\[[0-?]*[ -/]*[@-~]/g, "")
+    .replace(/\r/g, "\n")
+    .replace(/\n+/g, "\n");
+}
+
+function wrapLines(sourceLines, widthLimit) {
+  const wrapped = [];
+  for (const line of sourceLines) {
+    if (line.length <= widthLimit) {
+      wrapped.push(line);
+      continue;
+    }
+    for (let index = 0; index < line.length; index += widthLimit) {
+      wrapped.push(`${index === 0 ? "" : "  "}${line.slice(index, index + widthLimit)}`);
+    }
+  }
+  return wrapped;
+}
+
+function colorForLine(line) {
+  if (line.startsWith("$ ")) return "#8bd5ff";
+  if (/^(ContextOS debug|ContextOS report|Final additionalContext|Suggested files|Suggested workflows)/.test(line)) return "#ffd166";
+  if (/^(hook:|mcp:)/.test(line)) return "#9ad97f";
+  if (/^(codex|user|OpenAI Codex)/.test(line)) return "#c792ea";
+  if (/^#|^[-—]+$/.test(line)) return "#8a96a3";
+  return "#d8dee9";
+}
+
+function escapeXml(value) {
+  return String(value)
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}

package/package.json

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