@jokerized/tesserae 0.6.1

package/README.md

@@ -0,0 +1,34 @@
+# @jokerized/tesserae
+
+A thin **Node convenience wrapper** for [Tesserae](https://github.com/ca1773130n/Tesserae) — a context engine that compiles agent-ready knowledge from your project. The engine itself is a Python package; this wrapper just lets Node-centric users invoke it without leaving their toolchain.
+
+```bash
+npx @jokerized/tesserae --help
+npx @jokerized/tesserae init --yes
+npx @jokerized/tesserae compile
+```
+
+## Requirements
+
+- **Python 3.10+** on your PATH. The wrapper runs the real Python CLI; it does not reimplement it.
+
+## How it resolves the runner
+
+On each invocation, first match wins:
+
+1. `$TESSERAE_PYTHON -m tesserae` — explicit override (power users / CI).
+2. `python3` / `python` on PATH that can `import tesserae` — uses the Tesserae you already installed.
+3. `pipx run --spec tesserae==<this version> tesserae` — ephemeral, pinned to the matching Python release (first run installs it).
+4. Otherwise it prints install guidance (`pipx install tesserae`) and exits non-zero.
+
+Arguments, stdio, and the exit code are forwarded transparently, so `npx @jokerized/tesserae <anything>` behaves exactly like the real `tesserae` CLI.
+
+## Why a wrapper instead of a native package?
+
+Tesserae's engine (graph extraction, retrieval/PPR, the on-demand context compiler, MCP server) is Python. Reimplementing it in Node would fork the project; wrapping it keeps a single source of truth on [PyPI](https://pypi.org/project/tesserae/) and gives npm users a one-command entry point.
+
+The npm version tracks the Python release it pins (`@jokerized/tesserae@X.Y.Z` → `tesserae==X.Y.Z`).
+
+## License
+
+MIT — see the [main repository](https://github.com/ca1773130n/Tesserae).

package/bin/tesserae.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * Node convenience wrapper for Tesserae (a Python CLI).
+ *
+ * Resolution order for the runner, first match wins:
+ *   1. $TESSERAE_PYTHON -m tesserae          (explicit override; power users / tests)
+ *   2. <python> -m tesserae  for python3/python on PATH that can `import tesserae`
+ *      (fast path — uses the Tesserae the user already installed)
+ *   3. pipx run --spec tesserae==<this version> tesserae
+ *      (ephemeral, pinned to the matching Python release)
+ *   4. otherwise print install guidance and exit 1.
+ *
+ * Args, stdio, exit code, and SIGINT/SIGTERM are forwarded transparently so
+ * `npx @jokerized/tesserae <anything>` behaves exactly like the real CLI.
+ */
+
+const { spawnSync } = require("child_process");
+const path = require("path");
+
+const PKG_VERSION = require(path.join(__dirname, "..", "package.json")).version;
+const ARGS = process.argv.slice(2);
+
+function canImportTesserae(python) {
+  const probe = spawnSync(python, ["-c", "import tesserae"], {
+    stdio: "ignore",
+  });
+  return probe.status === 0;
+}
+
+function run(cmd, cmdArgs) {
+  const res = spawnSync(cmd, cmdArgs, { stdio: "inherit" });
+  if (res.error) {
+    // ENOENT etc. — signal "runner unavailable" to the caller.
+    return null;
+  }
+  // Mirror signal-terminated children as the conventional 128+signal code.
+  if (res.signal) {
+    return 128;
+  }
+  return res.status === null ? 1 : res.status;
+}
+
+function resolveAndRun() {
+  // 1. Explicit override.
+  const override = process.env.TESSERAE_PYTHON;
+  if (override) {
+    const code = run(override, ["-m", "tesserae", ...ARGS]);
+    if (code !== null) return code;
+  }
+
+  // 2. An already-installed Tesserae on a discoverable Python.
+  for (const python of ["python3", "python"]) {
+    if (canImportTesserae(python)) {
+      const code = run(python, ["-m", "tesserae", ...ARGS]);
+      if (code !== null) return code;
+    }
+  }
+
+  // 3. Ephemeral, version-pinned, via pipx.
+  const pipxProbe = spawnSync("pipx", ["--version"], { stdio: "ignore" });
+  if (pipxProbe.status === 0) {
+    process.stderr.write(
+      `[tesserae] no local install found — running tesserae==${PKG_VERSION} via pipx (first run installs it)\n`
+    );
+    const code = run(
+      "pipx",
+      ["run", "--spec", `tesserae==${PKG_VERSION}`, "tesserae", ...ARGS]
+    );
+    if (code !== null) return code;
+  }
+
+  // 4. Nothing worked — guide the user.
+  process.stderr.write(
+    [
+      "Tesserae requires Python 3.10+ and the `tesserae` package.",
+      "",
+      "Install it one of these ways, then re-run:",
+      "  pipx install tesserae        # recommended (isolated)",
+      "  pip install tesserae         # into the current environment",
+      "",
+      "Or set TESSERAE_PYTHON to a Python that already has it:",
+      "  TESSERAE_PYTHON=/path/to/python npx @jokerized/tesserae ...",
+      "",
+    ].join("\n")
+  );
+  return 1;
+}
+
+process.exit(resolveAndRun());

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@jokerized/tesserae",
+  "version": "0.6.1",
+  "description": "Node convenience wrapper for Tesserae — a context engine that compiles agent-ready knowledge from your project. Forwards to the Python CLI.",
+  "keywords": [
+    "tesserae",
+    "context-engine",
+    "knowledge-graph",
+    "llm",
+    "agents",
+    "cli",
+    "wrapper"
+  ],
+  "homepage": "https://github.com/ca1773130n/Tesserae#readme",
+  "bugs": {
+    "url": "https://github.com/ca1773130n/Tesserae/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ca1773130n/Tesserae.git",
+    "directory": "npm"
+  },
+  "license": "MIT",
+  "author": "Tesserae Contributors",
+  "type": "commonjs",
+  "bin": {
+    "tesserae": "bin/tesserae.js"
+  },
+  "files": [
+    "bin/tesserae.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}