@minhpnq1807/contextos 0.5.6 → 0.5.7

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.5.7
+
+- Adds thin passthrough commands `ctx ruler -- <args>` and `ctx skillshare -- <args>` for upstream admin/debug workflows without reimplementing those CLIs.
+- Preserves upstream output and exit status for passthrough commands, with install hints when the upstream binary is missing.
+
 ## 0.5.6
 
 - Adds visible `ctx install` progress from 0-100 so long model/file/skill embedding warmups no longer look stalled.

package/README.md

@@ -269,6 +269,20 @@ ctx sync --rules --no-import-codex-mcp
 
 `ctx sync --rules` is project-scoped. It writes `.ruler/ruler.toml` in the current project and lets Ruler generate agent files from that project source of truth. ContextOS runtime history still follows the project-path isolation model described below.
 
+## Upstream Passthrough
+
+ContextOS exposes thin passthrough commands for Ruler and skillshare admin/debug workflows:
+
+```bash
+ctx ruler -- apply --agents codex,claude,antigravity
+ctx ruler -- init
+ctx skillshare -- status
+ctx skillshare -- target list
+ctx skillshare -- doctor
+```
+
+Everything after `--` is forwarded unchanged to the upstream CLI. ContextOS does not reinterpret those args, and it preserves the upstream output and exit status. Use `ctx sync --rules` and `ctx sync --skills` for ContextOS-managed workflows; use passthrough when you need a native Ruler or skillshare command.
+
 ## Troubleshooting
 
 ### `ctx-mcp bridge socket not found`
@@ -324,6 +338,8 @@ This warning comes from a transitive dependency in the local embedding/WASM stac
 | `ctx sync --skills --dry-run` | Previews skillshare sync. | You want to inspect behavior before changing skill directories. | Runs `skillshare sync --dry-run` and skips embedding rebuild. |
 | `ctx sync --skills --no-collect` | Skips collecting existing agent skills into skillshare. | You already manage `~/.config/skillshare/skills` and only want to push it out. | Initializes/syncs skillshare without running `skillshare backup` or `skillshare collect --all`. |
 | `ctx embeddings warm -- "task"` | Prepares local semantic embedding caches. | First install, CI smoke checks, or after changing AGENTS.md/project files/skills. | Loads/downloads `Xenova/all-MiniLM-L6-v2` and writes rule, file-path, and skill vectors to `~/.ctx/contextos/embeddings.db`. |
+| `ctx ruler -- <args>` | Forwards args to the installed `ruler` CLI. | You need native Ruler commands such as `init`, `apply`, or `revert`. | Preserves Ruler stdout/stderr and exit status. |
+| `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. |
 
 ## Runtime Files

package/bin/ctx.js

@@ -24,6 +24,7 @@ import { installAntigravityMcp } from "../plugins/ctx/lib/antigravity-mcp.js";
 import { syncRules } from "../plugins/ctx/lib/ruler-sync.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";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const rootDir = path.resolve(__dirname, "..");
@@ -55,6 +56,8 @@ Usage:
   ctx sync --skills --no-collect
   ctx sync --skills --agents codex,claude,antigravity
   ctx embeddings warm -- "task"
+  ctx ruler -- <ruler args>
+  ctx skillshare -- <skillshare args>
   ctx --version
 `;
 }
@@ -451,6 +454,15 @@ try {
     } else {
       await syncRules({ cwd: process.cwd(), rootDir, args: args.slice(1) });
     }
+  } else if (command === "ruler" || command === "skillshare") {
+    const passthrough = parsePassthroughArgs(args);
+    const result = runPassthrough(passthrough);
+    if (result.signal) {
+      console.error(`${passthrough.command} terminated by signal ${result.signal}`);
+      process.exitCode = 1;
+    } else {
+      process.exitCode = result.status;
+    }
   } else {
     throw new Error(`Unknown command: ${command}\n\n${usage()}`);
   }

package/package.json

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

package/plugins/ctx/lib/passthrough.js

@@ -0,0 +1,50 @@
+import { spawnSync } from "node:child_process";
+
+const SUPPORTED_COMMANDS = new Set(["ruler", "skillshare"]);
+
+export function parsePassthroughArgs(args = []) {
+  const command = args[0];
+  if (!SUPPORTED_COMMANDS.has(command)) {
+    throw new Error(`Unsupported passthrough command: ${command || ""}`);
+  }
+
+  const separator = args.indexOf("--");
+  if (separator < 0) {
+    throw new Error(`Usage: ctx ${command} -- <${command} args>`);
+  }
+
+  return {
+    command,
+    args: args.slice(separator + 1)
+  };
+}
+
+export function runPassthrough({
+  command,
+  args = [],
+  spawn = spawnSync,
+  cwd = process.cwd(),
+  env = process.env
+} = {}) {
+  if (!SUPPORTED_COMMANDS.has(command)) {
+    throw new Error(`Unsupported passthrough command: ${command || ""}`);
+  }
+
+  const result = spawn(command, args, {
+    cwd,
+    env,
+    stdio: "inherit"
+  });
+
+  if (result.error) {
+    const hint = command === "ruler"
+      ? "Install it with `npm install -g @intellectronica/ruler`."
+      : "Install it with `curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/install.sh | sh`.";
+    throw new Error(`Failed to run ${command}: ${result.error.message}. ${hint}`);
+  }
+
+  return {
+    status: typeof result.status === "number" ? result.status : 1,
+    signal: result.signal || null
+  };
+}