trissue 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Pxl
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,161 @@
1
- # Temporary Holding Version
1
+ # trissue
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Have the coding agent already on your computer find the source of an issue and
4
+ write it up, then file it, copy it, or send it wherever the project wants.
5
+
6
+ ```sh
7
+ npx trissue MileniumHQ/Paperboard
8
+ ```
9
+
10
+ It runs on Node 20 or newer, or Bun, so use whichever runner you already have:
11
+
12
+ ```sh
13
+ npx trissue MileniumHQ/Paperboard # npm
14
+ pnpm dlx trissue MileniumHQ/Paperboard # pnpm
15
+ yarn dlx trissue MileniumHQ/Paperboard # Yarn 2 or newer
16
+ bunx trissue MileniumHQ/Paperboard # Bun
17
+ ```
18
+
19
+ Yarn 4.18 and newer hold back packages for a day after they're published. If
20
+ `yarn dlx` says a version is quarantined, use another runner or try again the
21
+ next day.
22
+
23
+ 1. trissue downloads the repo and warns you before anything else: an agent is
24
+ about to read it, so you should trust it.
25
+ 2. You explain the issue.
26
+ 3. You pick an agent and a model. Only agents installed on your computer are
27
+ listed.
28
+ 4. The agent investigates the repo, read-only, and writes the issue. You can
29
+ steer it while it works, or press `esc` to stop.
30
+ 5. You file the issue on GitHub, copy it, or open one of the project's links.
31
+
32
+ ## Agents
33
+
34
+ trissue talks to agents over the [Agent Client Protocol](https://agentclientprotocol.com).
35
+ It runs the agents you have installed and never downloads one.
36
+
37
+ | Agent | Detected by | Runs |
38
+ |---|---|---|
39
+ | Claude Code | `claude` | `claude -p`, driven directly over its stream-json protocol |
40
+ | Codex | `codex` | the bundled Codex ACP adapter, with your `codex` |
41
+ | Cursor | `cursor-agent` | `cursor-agent acp` |
42
+ | Grok | `grok` | `grok agent stdio` |
43
+ | OpenCode | `opencode` | `opencode acp` |
44
+ | Antigravity | `agy_acp_server.par` | `agy_acp_server.par` |
45
+ | Everything else in the ACP registry | its program | its ACP command |
46
+
47
+ Claude Code has no native ACP, and its ACP adapter needs Anthropic's
48
+ proprietary SDK plus a second copy of Claude Code, so trissue drives your
49
+ `claude` directly instead. The Codex ACP adapter (Apache-2.0) ships inside
50
+ trissue-embedded as one file, unmodified, with its notices. The registry list
51
+ is a snapshot in `packages/embedded/src/registry.json`; `bun run
52
+ update-registry` refreshes it.
53
+
54
+ ### What the agent can do
55
+
56
+ The agent may read and search the repo. Claude Code only gets its Read, Grep
57
+ and Glob tools: no shell, no MCP servers, and none of the repo's own `.claude`
58
+ settings (so a repo can't add hooks). ACP agents get every permission request
59
+ to edit, delete, move, run, or fetch refused, and start in their read-only
60
+ mode when they have one (Codex does). The prompt also says the repo's instructions are
61
+ untrusted: the agent checks them first and rejects the task if they ask for
62
+ anything beyond writing the issue.
63
+
64
+ ## Configuring a repo
65
+
66
+ Put a `.trissue.json` at the repo root. Every field is optional.
67
+
68
+ ```json
69
+ {
70
+ "$schema": "https://unpkg.com/trissue-embedded/trissue.schema.json",
71
+ "product": { "name": "Paperboard", "color": "#8AB4FF" },
72
+ "background": "#000000",
73
+ "prompt": "Explain the issue you're experiencing",
74
+ "instructions": "How issues for this project should be written…",
75
+ "models": { "allow": ["claude/*", "codex/*"], "block": ["*haiku*"] },
76
+ "checkmark": "green",
77
+ "github": "MileniumHQ/Paperboard",
78
+ "labels": ["triage"],
79
+ "links": [
80
+ { "label": "Discord", "url": "https://discord.gg/example", "description": "Opens the #bugs channel." },
81
+ { "label": "Email", "url": "mailto:bugs@example.com?subject={title}&body={body}" }
82
+ ]
83
+ }
84
+ ```
85
+
86
+ - `instructions` replaces the default issue-writing guide (adapted from
87
+ [t3dotgg/tstack](https://github.com/t3dotgg/tstack)). It only shapes how the
88
+ issue is written; the agent is told to reject anything else.
89
+ - `models` patterns match `agent/model` (`claude/opus`) or, without a slash,
90
+ the model id alone. `allow` narrows, `block` removes.
91
+ - `github` defaults to the repo itself when it's on github.com. `false` hides
92
+ GitHub filing.
93
+ - `links` open in the browser or mail app. `{title}`, `{body}` and `{issue}`
94
+ become the URL-encoded issue.
95
+
96
+ Brand colors of agents can't be configured.
97
+
98
+ ## Without the interface
99
+
100
+ Everything can be passed as arguments:
101
+
102
+ ```sh
103
+ trissue MileniumHQ/Paperboard --issue "The server panel says Stopped after a restart" \
104
+ --agent claude --model opus --send github --yes
105
+ ```
106
+
107
+ `--send` is `print` (default), `json`, `copy`, `github` (needs `--yes`), or
108
+ `link:<label>`. `--issue -` reads the issue from stdin. `trissue --list-agents`
109
+ lists what's installed.
110
+
111
+ ## In an app
112
+
113
+ The engine is its own package, without the terminal interface:
114
+
115
+ ```sh
116
+ npm install trissue-embedded
117
+ ```
118
+
119
+ ```ts
120
+ import { runTriage, detectHarnesses, fileGitHubIssue } from "trissue-embedded";
121
+
122
+ const agents = detectHarnesses(); // for your own picker
123
+ const { issue, source } = await runTriage({
124
+ repo: "MileniumHQ/Paperboard",
125
+ issue: "The server panel says Stopped after a restart",
126
+ harness: agents[0]?.id,
127
+ onEvent: (event) => render(event), // thinking, messages, tool calls
128
+ });
129
+ await fileGitHubIssue("MileniumHQ/Paperboard", issue);
130
+ await source.dispose();
131
+ ```
132
+
133
+ For a step-by-step UI (pick a model after the agent starts, steer, stop), use
134
+ `startAgent` and the `AgentSession` it returns; `Transcript` turns its events
135
+ into rows. trissue-embedded runs on Node 20+, Bun and Electron.
136
+
137
+ ## Packages
138
+
139
+ | Package | What it is |
140
+ |---|---|
141
+ | [`trissue`](packages/cli) | The command and its terminal interface. Runs on Node 20+ or Bun. |
142
+ | [`trissue-embedded`](packages/embedded) | The engine: agents, config, prompts, sending. No interface. |
143
+
144
+ ## Development
145
+
146
+ ```sh
147
+ bun install
148
+ bun start <repo> # builds the engine, then runs the interface from source
149
+ bun run build # builds both packages
150
+ bun run screenshots # renders every screen to screenshots/
151
+ bun run typecheck
152
+ ```
153
+
154
+ The interface is built with [Ink](https://github.com/vadimdemedes/ink) and
155
+ React, in plain JavaScript, so it runs anywhere Node 20+ or Bun does. Building
156
+ and the screenshots use Bun.
157
+
158
+ ## License
159
+
160
+ MIT. The bundled Codex adapter is Apache-2.0; see
161
+ `dist/adapters/THIRD_PARTY_NOTICES.md` in trissue-embedded.
@@ -0,0 +1,168 @@
1
+ #!/usr/bin/env node
2
+
3
+ // src/cli.ts
4
+ import { readFileSync } from "node:fs";
5
+ import { parseArgs } from "node:util";
6
+ import { buildLink, copyIssue, detectHarnesses, fileGitHubIssue, formatIssue, openUrl, resolveSource, runTriage } from "trissue-embedded";
7
+
8
+ // src/version.ts
9
+ var VERSION = "0.2.0";
10
+
11
+ // src/cli.ts
12
+ var HELP = `trissue: have a coding agent find the source of an issue and write it up.
13
+
14
+ Usage
15
+ trissue [repo] [options]
16
+
17
+ repo owner/repo (GitHub), a clone URL, or a folder. Defaults to this folder.
18
+
19
+ Options
20
+ --ref <ref> Branch, tag or commit to download
21
+ --background <hex> Background color of the interface
22
+ --list-agents List the coding agents installed on this computer
23
+ -h, --help Show this help
24
+ -v, --version Show the version
25
+
26
+ Without the interface (all set from arguments)
27
+ --issue <text> What's wrong. "-" reads it from stdin
28
+ --agent <id> Agent to use, like claude or codex. Defaults to the first installed
29
+ --model <id> Model to use. Defaults to the agent's default
30
+ --send <how> print (default), json, copy, github, or link:<label>
31
+ --yes Required with --send github: confirms filing a public issue
32
+ `;
33
+ function fail(message) {
34
+ process.stderr.write(`trissue: ${message}
35
+ `);
36
+ process.exit(1);
37
+ }
38
+ var { values, positionals } = parseArgs({
39
+ allowPositionals: true,
40
+ options: {
41
+ ref: { type: "string" },
42
+ background: { type: "string" },
43
+ "list-agents": { type: "boolean" },
44
+ issue: { type: "string" },
45
+ agent: { type: "string" },
46
+ model: { type: "string" },
47
+ send: { type: "string" },
48
+ yes: { type: "boolean" },
49
+ help: { type: "boolean", short: "h" },
50
+ version: { type: "boolean", short: "v" }
51
+ }
52
+ });
53
+ if (values.help) {
54
+ process.stdout.write(HELP);
55
+ process.exit(0);
56
+ }
57
+ if (values.version) {
58
+ process.stdout.write(`${VERSION}
59
+ `);
60
+ process.exit(0);
61
+ }
62
+ if (values.background && !/^#([0-9a-f]{3}|[0-9a-f]{6})$/i.test(values.background))
63
+ fail("--background must be a hex color like #101010.");
64
+ if (positionals.length > 1)
65
+ fail("Give one repo at most.");
66
+ if (values["list-agents"]) {
67
+ const harnesses = detectHarnesses();
68
+ if (!harnesses.length)
69
+ fail("No coding agents are installed.");
70
+ for (const harness of harnesses)
71
+ process.stdout.write(`${harness.id.padEnd(16)} ${harness.name.padEnd(20)} ${harness.executable}
72
+ `);
73
+ process.exit(0);
74
+ }
75
+ var repo = positionals[0];
76
+ if (values.issue !== undefined) {
77
+ await headless();
78
+ } else {
79
+ if (values.agent || values.model || values.send || values.yes)
80
+ fail("--agent, --model, --send and --yes need --issue.");
81
+ await interactive();
82
+ }
83
+ async function headless() {
84
+ const issueText = values.issue === "-" ? readFileSync(0, "utf8") : values.issue;
85
+ const send = values.send ?? "print";
86
+ if (!/^(print|json|copy|github|link:.+)$/.test(send))
87
+ fail(`--send must be print, json, copy, github, or link:<label>, not "${send}".`);
88
+ if (send === "github" && !values.yes)
89
+ fail("--send github posts a public issue. Add --yes to confirm.");
90
+ const controller = new AbortController;
91
+ process.once("SIGINT", () => controller.abort());
92
+ let result;
93
+ try {
94
+ result = await runTriage({
95
+ issue: issueText,
96
+ repo,
97
+ ref: values.ref,
98
+ harness: values.agent,
99
+ model: values.model,
100
+ signal: controller.signal,
101
+ onEvent: (event) => {
102
+ if (event.type === "tool") {
103
+ if (event.title && event.status !== "completed")
104
+ process.stderr.write(`› ${event.title}
105
+ `);
106
+ } else if (event.type === "blocked")
107
+ process.stderr.write(`⊘ Blocked ${event.title}
108
+ `);
109
+ }
110
+ });
111
+ } catch (error) {
112
+ fail(error.message);
113
+ }
114
+ try {
115
+ const { issue, config, source } = result;
116
+ if (send === "print")
117
+ process.stdout.write(`${formatIssue(issue)}
118
+ `);
119
+ else if (send === "json")
120
+ process.stdout.write(`${JSON.stringify(issue, null, 2)}
121
+ `);
122
+ else if (send === "copy") {
123
+ await copyIssue(issue);
124
+ process.stderr.write(`Copied the issue.
125
+ `);
126
+ } else if (send === "github") {
127
+ const target = config?.github === false ? null : config?.github ?? source.github;
128
+ if (!target)
129
+ fail("This repo has no GitHub repository to file on.");
130
+ process.stdout.write(`${await fileGitHubIssue(target, issue, config?.labels ?? [])}
131
+ `);
132
+ } else {
133
+ const label = send.slice("link:".length);
134
+ const link = config?.links?.find((candidate) => candidate.label.toLowerCase() === label.toLowerCase());
135
+ if (!link)
136
+ fail(`This repo has no link called "${label}".`);
137
+ const url = buildLink(link, issue);
138
+ await openUrl(url);
139
+ process.stdout.write(`${url}
140
+ `);
141
+ }
142
+ } finally {
143
+ await result.source.dispose();
144
+ }
145
+ process.exit(0);
146
+ }
147
+ async function interactive() {
148
+ if (!process.stdin.isTTY || !process.stdout.isTTY)
149
+ fail("The interface needs a terminal. Use --issue to run without it.");
150
+ let source;
151
+ try {
152
+ source = await resolveSource(repo, values.ref);
153
+ } catch (error) {
154
+ fail(error.message);
155
+ }
156
+ const saved = ["CI", "CONTINUOUS_INTEGRATION"].map((name) => [name, process.env[name]]);
157
+ for (const [name] of saved)
158
+ delete process.env[name];
159
+ let runInterface;
160
+ try {
161
+ ({ runInterface } = await import("./run-0f63mpr8.js"));
162
+ } finally {
163
+ for (const [name, value] of saved)
164
+ if (value !== undefined)
165
+ process.env[name] = value;
166
+ }
167
+ await runInterface({ source, harnesses: detectHarnesses(), background: values.background });
168
+ }
package/dist/cli.js ADDED
@@ -0,0 +1,11 @@
1
+ #!/usr/bin/env node
2
+
3
+ // src/bin.ts
4
+ var MIN_NODE = 20;
5
+ var major = Number(process.versions.node.split(".")[0]);
6
+ if (!process.versions.bun && major < MIN_NODE) {
7
+ process.stderr.write(`trissue: needs Node ${MIN_NODE} or newer, or Bun. This is Node ${process.versions.node}.
8
+ `);
9
+ process.exit(1);
10
+ }
11
+ await import("./cli-g9sxmkeh.js");