@andrew-codes/twg-axi 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrew Smith
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,81 @@
+# twg-axi
+
+A drop-in wrapper for Atlassian's [`twg`](https://www.npmjs.com/package/twg) CLI that emits
+[TOON](https://toonformat.dev) instead of JSON on stdout.
+
+`twg-axi` mirrors `twg` exactly: every command, flag, and argument is forwarded to the real
+`twg` binary unchanged. The only difference is output encoding. Any time `twg` would write raw
+JSON to stdout (`--output json` or `--output jsonl`), `twg-axi` captures that JSON and re-emits
+it as TOON, which is roughly 30-60% fewer tokens for an LLM to read than the equivalent JSON.
+Everything else - plain text output, tables, `--output-summary`'s YAML envelope, errors, exit
+codes, and stdin/stdout/stderr stream behavior - passes through from `twg` unaltered.
+
+`twg-axi` does not implement any `twg` functionality itself. It is a thin subprocess wrapper
+around the installed `twg` binary plus a JSON-to-TOON conversion step at the output boundary.
+
+## Requirements
+
+- Node.js >= 18
+- The [`twg` CLI](https://www.npmjs.com/package/twg) installed and authenticated on your `PATH`
+
+## Installation
+
+```sh
+npm install -g @andrew-codes/twg-axi
+```
+
+This installs a `twg-axi` executable alongside `twg`. It does not install or configure `twg`
+itself - `twg-axi` requires `twg` to already be present and authenticated.
+
+## Usage
+
+Run `twg-axi` exactly as you would run `twg`, substituting the binary name:
+
+```sh
+twg-axi jira issue list --project ABC --output json
+```
+
+Any flag, subcommand, or argument accepted by `twg` is accepted identically by `twg-axi` and
+forwarded through unchanged. See `twg --help` (or `twg-axi --help`, which is the same thing) for
+the full command surface.
+
+### JSON becomes TOON
+
+```sh
+$ twg jira issue list --project ABC --output json
+{"items":[{"key":"ABC-1","summary":"Fix auth bug"},{"key":"ABC-2","summary":"Add pagination"}]}
+
+$ twg-axi jira issue list --project ABC --output json
+items[2]{key,summary}:
+  ABC-1,Fix auth bug
+  ABC-2,Add pagination
+```
+
+The same applies to `--output jsonl`, where each JSON record is converted to its own TOON block.
+
+### Everything else passes through unchanged
+
+Default text output, tables, `--output json --output-summary` (which emits a YAML envelope, not
+raw JSON), error messages, and exit codes are all identical to running `twg` directly.
+
+## How it works
+
+`twg-axi` spawns `twg` as a subprocess with the exact argv it was given.
+
+- When `--output`/`-o` is not `json` or `jsonl` (or `--output-summary` is set, which makes `twg`
+  emit YAML instead of raw JSON), stdin/stdout/stderr are inherited directly from `twg` so
+  behavior - including streaming and TTY detection - is identical to running `twg` on its own.
+- When `--output json` or `--output jsonl` is requested without `--output-summary`, `twg-axi`
+  captures `twg`'s stdout, parses it as JSON, and re-encodes it with
+  [`@toon-format/toon`](https://www.npmjs.com/package/@toon-format/toon) before writing it to
+  stdout. If the captured output isn't valid JSON (for example, `twg` exited before writing a
+  payload), it is passed through unchanged rather than dropped.
+
+Exit codes and signals (`SIGINT`, `SIGTERM`, `SIGHUP`) are forwarded to the underlying `twg`
+process in both cases.
+
+## Contributing
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md) for local development setup (Yarn PnP /
+zero-installs) and [`docs/release-process.md`](docs/release-process.md) for how releases are
+cut and published.

package/dist/bin/twg-axi.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { main } from "../cli.js";
+main(process.argv.slice(2))
+    .then((code) => {
+    process.exitCode = code;
+})
+    .catch((error) => {
+    const message = error instanceof Error ? (error.stack ?? error.message) : String(error);
+    process.stderr.write(`${message}\n`);
+    process.exitCode = 1;
+});

package/dist/cli.js

@@ -0,0 +1,50 @@
+import { spawn } from "node:child_process";
+import { constants } from "node:os";
+import { needsToonConversion, parseOutputMode } from "./output-mode.js";
+import { convertToToon } from "./toon-convert.js";
+// Overridable only so tests can point at a fixture binary instead of the real twg CLI.
+const TWG_BIN = process.env.TWG_AXI_BIN ?? "twg";
+const FORWARDED_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
+function reportSpawnFailure(error) {
+    if (error.code === "ENOENT") {
+        process.stderr.write(`twg-axi: could not find "${TWG_BIN}" on PATH. Install the twg CLI and ensure it is reachable.\n`);
+        return 127;
+    }
+    process.stderr.write(`twg-axi: failed to run "${TWG_BIN}": ${error.message}\n`);
+    return 1;
+}
+function exitCodeFor(code, signal) {
+    if (signal)
+        return 128 + (constants.signals[signal] ?? 0);
+    return code ?? 1;
+}
+async function runPassthrough(argv) {
+    return new Promise((resolve) => {
+        const child = spawn(TWG_BIN, argv, { stdio: "inherit" });
+        for (const signal of FORWARDED_SIGNALS) {
+            process.on(signal, () => child.kill(signal));
+        }
+        child.on("error", (error) => resolve(reportSpawnFailure(error)));
+        child.on("close", (code, signal) => resolve(exitCodeFor(code, signal)));
+    });
+}
+async function runWithConversion(argv, format) {
+    return new Promise((resolve) => {
+        const child = spawn(TWG_BIN, argv, { stdio: ["inherit", "pipe", "inherit"] });
+        const chunks = [];
+        for (const signal of FORWARDED_SIGNALS) {
+            process.on(signal, () => child.kill(signal));
+        }
+        child.stdout.on("data", (chunk) => chunks.push(chunk));
+        child.on("error", (error) => resolve(reportSpawnFailure(error)));
+        child.on("close", (code, signal) => {
+            const raw = Buffer.concat(chunks).toString("utf8");
+            process.stdout.write(convertToToon(raw, format));
+            resolve(exitCodeFor(code, signal));
+        });
+    });
+}
+export async function main(argv) {
+    const mode = parseOutputMode(argv);
+    return needsToonConversion(mode) ? runWithConversion(argv, mode.format) : runPassthrough(argv);
+}

package/dist/output-mode.js

@@ -0,0 +1,42 @@
+const SUMMARY_LEVELS = new Set(["stats", "auto", "inline"]);
+/**
+ * Scans raw argv for twg's global --output/-o and --output-summary flags without
+ * reimplementing twg's own argument parser. Used only to decide whether stdout will
+ * carry raw JSON that needs TOON conversion; the argv is always forwarded to twg unchanged.
+ */
+export function parseOutputMode(argv) {
+    let format = "text";
+    let summary = false;
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === "--output" || token === "-o") {
+            format = argv[i + 1] ?? format;
+            i++;
+            continue;
+        }
+        if (token.startsWith("--output=")) {
+            format = token.slice("--output=".length);
+            continue;
+        }
+        if (token.startsWith("-o") && token.length > 2) {
+            format = token.slice(2);
+            continue;
+        }
+        if (token === "--output-summary") {
+            summary = true;
+            const next = argv[i + 1];
+            if (next !== undefined && SUMMARY_LEVELS.has(next))
+                i++;
+            continue;
+        }
+        if (token.startsWith("--output-summary=")) {
+            summary = true;
+            continue;
+        }
+    }
+    return { format, summary };
+}
+/** twg only emits raw JSON on stdout for --output json/jsonl without --output-summary. */
+export function needsToonConversion(mode) {
+    return (mode.format === "json" || mode.format === "jsonl") && !mode.summary;
+}

package/dist/toon-convert.js

@@ -0,0 +1,23 @@
+import { encode } from "@toon-format/toon";
+/**
+ * Converts captured twg stdout to TOON. Falls back to returning the input unchanged
+ * when it isn't valid JSON (e.g. twg exited before writing a payload) so the wrapper
+ * never fabricates output that didn't come from twg.
+ */
+export function convertToToon(raw, format) {
+    const text = raw.trim();
+    if (!text)
+        return raw;
+    try {
+        if (format === "jsonl") {
+            const lines = text.split(/\r?\n/).filter((line) => line.trim().length > 0);
+            const blocks = lines.map((line) => encode(JSON.parse(line)));
+            return `${blocks.join("\n")}\n`;
+        }
+        const data = JSON.parse(text);
+        return `${encode(data)}\n`;
+    }
+    catch {
+        return raw;
+    }
+}

package/docs/release-process.md

@@ -0,0 +1,68 @@
+# Release process
+
+`@andrew-codes/twg-axi` publishes to npm automatically. There is no manual version bump
+and no manual `npm publish`.
+
+## How a release happens
+
+Every push to `main` (i.e. every merged PR) runs `.github/workflows/release.yml`:
+
+1. Check out the repo with full history and tags.
+2. Install with Yarn PnP (`yarn install --immutable`) and run the full verification suite
+   (typecheck, tests, lint if present). If any step fails, the workflow stops here - nothing
+   is published, versioned, or tagged.
+3. Walk the commits since the last version tag and compute the next semantic version from
+   their messages (see below).
+4. Bump `package.json` to that version, build, and publish the package to npm under the
+   `@andrew-codes` scope.
+5. Only if publishing succeeds: commit the version bump back to `main` (with a `[skip ci]`
+   marker so it doesn't retrigger the workflow) and create + push a git tag for the new
+   version, then create a GitHub release for that tag.
+
+## How the version is computed
+
+The workflow uses [Conventional Commits](https://www.conventionalcommits.org/) prefixes on
+commit messages to decide the bump type:
+
+| Commit message pattern                                  | Bump  |
+| --------------------------------------------------------- | ----- |
+| `fix: ...`                                                 | patch |
+| `feat: ...`                                                | minor |
+| Any commit with a `BREAKING CHANGE:` footer, or `!` after the type/scope (e.g. `feat!:`) | major |
+| No commits since the last tag match a recognized prefix   | patch |
+
+Only commits since the most recent version tag are considered. If several commits qualify
+for different bump levels, the highest one wins (major > minor > patch).
+
+To land a release at the bump level you want, write your commit messages accordingly:
+
+```
+fix: correct exit code passthrough on SIGTERM
+feat: support --output jsonl passthrough
+feat!: drop Node 16 support
+
+BREAKING CHANGE: minimum supported Node.js version is now 18
+```
+
+Commits that don't follow this convention (e.g. `chore:`, `docs:`, or unprefixed messages)
+don't influence the bump; if a release contains only such commits, it still ships as a patch.
+
+## Local development under Yarn PnP / zero-installs
+
+This project uses Yarn Plug'n'Play with zero-installs: `.pnp.cjs`, `.yarn/cache`, and
+`.yarn/releases` are committed to the repo, so `yarn install` after a fresh clone does not
+hit the network for anything already in the cache and does not create a `node_modules`
+directory.
+
+Practical implications:
+
+- Don't `rm -rf node_modules` to "reset" things - there isn't one. If something seems stale,
+  `yarn install` again.
+- Adding or upgrading a dependency (`yarn add`, `yarn up`) updates `.pnp.cjs`,
+  `yarn.lock`, and `.yarn/cache` together; commit all three.
+- Editors need the Yarn PnP SDK/IDE integration to resolve TypeScript correctly (see
+  [`CONTRIBUTING.md`](../CONTRIBUTING.md) for setup).
+- Tools that read `node_modules` directly instead of through Node's module resolution (some
+  native binaries, some editor plugins) may need a package marked
+  `dependenciesMeta.<name>.unplugged: true` in `package.json` to force it to be extracted to
+  a real folder under `.yarn/unplugged` instead of read from the zip cache.

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@andrew-codes/twg-axi",
+  "version": "0.1.0",
+  "description": "Drop-in wrapper for Atlassian's twg CLI that emits TOON instead of JSON on stdout",
+  "type": "module",
+  "license": "MIT",
+  "author": "Andrew Smith <andrew@andrew.codes>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/andrew-codes/atlassian-twg-axi.git"
+  },
+  "bin": "./dist/bin/twg-axi.js",
+  "files": [
+    "dist",
+    "README.md",
+    "docs"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && chmod +x dist/bin/twg-axi.js",
+    "pretest": "yarn build",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint ."
+  },
+  "dependencies": {
+    "@toon-format/toon": "^4.1.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^22.10.0",
+    "conventional-commits-parser": "^7.1.2",
+    "eslint": "^10.11.0",
+    "globals": "^17.12.0",
+    "semver": "^7.6.3",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.70.1",
+    "vite": "^8.0.0",
+    "vitest": "5.0.1"
+  },
+  "packageManager": "yarn@4.18.1"
+}