triss-coworker 0.13.0

package/bin/triss.js

@@ -0,0 +1,263 @@
+#!/usr/bin/env node
+const [nodeMajor] = process.versions.node.split('.').map(Number);
+if (nodeMajor < 18) {
+  process.stderr.write(
+    `triss requires Node.js >= 18 (you are on ${process.versions.node}).\n` +
+      `Upgrade via nvm/fnm or https://nodejs.org/.\n`,
+  );
+  process.exit(1);
+}
+
+import { Command } from 'commander';
+import pc from 'picocolors';
+import { runAsk } from '../src/commands/ask.js';
+import { runWrite } from '../src/commands/write.js';
+import { runExtract } from '../src/commands/extract.js';
+import { runFetch } from '../src/commands/fetch.js';
+import { runReview } from '../src/commands/review.js';
+import { runChat } from '../src/commands/chat.js';
+import { runUsage } from '../src/commands/usage.js';
+import {
+  runMcpServe,
+  runMcpInstall,
+  runMcpUninstall,
+  runMcpStatus,
+} from '../src/commands/mcp.js';
+import { runCommitMsg } from '../src/commands/commit-msg.js';
+import { runInit } from '../src/commands/init.js';
+import { runStatus } from '../src/commands/status.js';
+import { runCompletion } from '../src/commands/completion.js';
+import {
+  runWizard,
+  runSet,
+  runGet,
+  runList,
+  runPath,
+  runEdit,
+  runUnset,
+} from '../src/commands/config.js';
+import { loadIntegrations } from '../src/integrations/_registry.js';
+
+const program = new Command();
+program
+  .name('triss')
+  .description(
+    'Cheap DeepSeek coworker for AI coding agents. Delegate bulk reads, ' +
+      'boilerplate generation, chat extraction, and tracker I/O to save tokens.',
+  )
+  .version('0.12.1');
+
+program
+  .command('init')
+  .description('Add the triss delegation block to your project (or globally)')
+  .option('-g, --global', 'install into the target agent global rules file instead of the current project')
+  .option('-t, --target <agent>', 'target agent (claude | codex | both); omit for an interactive prompt')
+  .option('-f, --force', 'force-replace an existing triss block without diffing')
+  .option('-s, --setup', 'after writing CLAUDE.md, run `triss config wizard` to fill in credentials')
+  .action(wrap(runInit));
+
+program
+  .command('ask')
+  .description('Delegate bulk reading (files, URLs, and/or piped stdin) to DeepSeek; returns a structured summary')
+  .option('-p, --paths <paths...>', 'files or globs to read')
+  .option('-u, --urls <urls...>', 'http(s) URLs to fetch and convert to markdown')
+  .option('--stdin', 'read piped stdin as an additional source (for `cmd | triss ask --stdin ...`)')
+  .requiredOption('-q, --question <text>', 'question to answer about the corpus')
+  .option('-m, --model <name>', 'model preset (flash | pro) or full model id')
+  .option('--max-tokens <n>', 'token budget for reasoning + answer', (v) => parseInt(v, 10), 8192)
+  .option('--system <text>', 'override the system prompt')
+  .option('--no-stream', "disable streaming output (default streams when stdout is a TTY)")
+  .action(wrap(runAsk));
+
+program
+  .command('write')
+  .description('Delegate boilerplate generation to DeepSeek')
+  .requiredOption('-s, --spec <text>', 'what to write')
+  .requiredOption('-t, --target <path>', 'output file path')
+  .option('-c, --context <path>', 'reference file to mimic in style')
+  .option('-m, --model <name>', 'model preset (flash | pro) or full model id')
+  .option('--max-tokens <n>', 'token budget for reasoning + output', (v) => parseInt(v, 10), 16384)
+  .action(wrap(runWrite));
+
+program
+  .command('extract')
+  .description('Convert Claude Code JSONL transcripts into readable text')
+  .argument('<jsonl>', 'path to a .jsonl session file')
+  .option('-o, --output <path>', 'write to file instead of stdout')
+  .action((jsonl, opts) => wrap(runExtract)({ jsonl, ...opts }));
+
+program
+  .command('fetch')
+  .description('Fetch URL(s) and return readable markdown; --question summarises via DeepSeek')
+  .argument('<urls...>', 'one or more http(s) URLs')
+  .option('-q, --question <text>', 'have DeepSeek summarise the fetched corpus')
+  .option('-m, --model <name>', 'model preset (flash | pro) or full model id')
+  .option('--max-tokens <n>', 'token budget for the summary')
+  .option('--timeout <ms>', 'per-request timeout in ms (default 30000)')
+  .option('--json', 'output JSON array of {url, markdown}')
+  .action((urls, opts) => wrap(runFetch)(urls, opts));
+
+program
+  .command('chat [prompt]')
+  .description('Ask the worker model anything — no corpus, just a bare prompt.')
+  .option('--stdin', 'read prompt from piped stdin instead of [prompt] arg')
+  .option('-s, --system <text>', 'system prompt (e.g. role / persona)')
+  .option('-m, --model <name>', 'model preset (flash | pro) or full model id')
+  .option('--max-tokens <n>', 'token budget (default 4096)')
+  .option('--no-stream', 'disable streaming output')
+  .action((prompt, opts) => wrap(runChat)(prompt, opts));
+
+program
+  .command('commit-msg')
+  .description('Generate a Git commit message from staged changes (Conventional Commits by default).')
+  .option('--apply', 'run `git commit -m <generated>` immediately instead of printing')
+  .option('--no-conventional', 'use a free-form commit subject instead of Conventional Commits')
+  .option('--type <type>', 'force the conventional type (feat | fix | refactor | …)')
+  .option('--scope <scope>', 'force the conventional scope')
+  .option('-m, --model <name>', 'model preset (flash | pro) or full id')
+  .option('--max-tokens <n>', 'token budget (default 2048)')
+  .action(wrap(runCommitMsg));
+
+program
+  .command('review [pr]')
+  .description('Code review via DeepSeek. No arg: current branch vs default base. With <pr>: GitHub PR via gh.')
+  .option('-b, --base <branch>', 'compare against this branch (default: auto-detect origin/HEAD or main/master/develop)')
+  .option('--skip-issue', "don't try to look up a Jira/Linear ticket from the branch/PR title")
+  .option('-q, --question <text>', 'override the default review question')
+  .option('-m, --model <name>', 'model preset (flash | pro) or full model id (default: pro)')
+  .option('--max-tokens <n>', 'token budget for the review (default 8192)')
+  .option('--no-stream', 'disable streaming output')
+  .action((pr, opts) => wrap(runReview)(pr, opts));
+
+program
+  .command('usage')
+  .description('Cumulative cost / token usage summary across all triss calls')
+  .option('--since <period>', 'period like 24h, 7d, 4w (default 24h)')
+  .option('--month', 'shortcut for --since 30d')
+  .option('--by-project', 'break down by working directory')
+  .option('--by-model', 'break down by model name')
+  .option('--by-label', 'break down by call source (ask, review, chat, …)')
+  .option('--json', 'dump raw log records as JSON')
+  .option('--reset', 'clear the usage log (cannot be undone)')
+  .action(wrap(runUsage));
+
+program
+  .command('status')
+  .description('Show current configuration: API key, models, .env sources')
+  .action(wrap(runStatus));
+
+program
+  .command('completion <shell>')
+  .description('Print shell completion script (bash | zsh). eval `triss completion bash`')
+  .action((shell) => wrap(runCompletion)(shell, program));
+
+const config = program
+  .command('config')
+  .description('Manage credentials in ~/.config/triss/.env (global) or ./.triss.env (project)');
+
+config
+  .command('wizard [target]')
+  .description('Interactive setup. Optional target: deepseek | jira | linear | …')
+  .option('-g, --global', 'save to ~/.config/triss/.env (default if not asked)')
+  .option('-l, --local', 'save to ./.triss.env (project-local override)')
+  .option('-f, --force', 're-prompt for keys that are already set')
+  .option('--standard', 'API key + one model only — skip the standard/advanced prompt')
+  .option('--advanced', 'full wizard with presets, base URL, integrations — skip the prompt')
+  .action(wrap(runWizard));
+
+config
+  .command('set <KEY> [value]')
+  .description('Set a single variable. Without value, prompts (masked for *_KEY/_TOKEN). Use "-" to read from stdin.')
+  .option('-g, --global', 'save to global env file')
+  .option('-l, --local', 'save to project env file (./.triss.env)')
+  .action(wrap(runSet));
+
+config
+  .command('get <KEY>')
+  .description('Print the active value (masked for secrets)')
+  .option('-g, --global', 'check only the global file')
+  .option('-l, --local', 'check only the project file')
+  .action(wrap(runGet));
+
+config
+  .command('list')
+  .description('List variables from all (or one) env file')
+  .option('-g, --global', 'only the global file')
+  .option('-l, --local', 'only the project file')
+  .action(wrap(runList));
+
+config
+  .command('path')
+  .description('Print path(s) of triss env file(s)')
+  .option('-g, --global', 'only the global path')
+  .option('-l, --local', 'only the project path')
+  .action(wrap(runPath));
+
+config
+  .command('edit')
+  .description('Open the env file in $EDITOR ($VISUAL > $EDITOR > vi)')
+  .option('-g, --global', 'edit the global file')
+  .option('-l, --local', 'edit the project file')
+  .action(wrap(runEdit));
+
+config
+  .command('unset <KEY>')
+  .description('Remove a variable from an env file')
+  .option('-g, --global', 'global file')
+  .option('-l, --local', 'project file')
+  .action(wrap(runUnset));
+
+function wrap(fn) {
+  return async (...args) => {
+    try {
+      await fn(...args);
+    } catch (err) {
+      process.stderr.write(pc.red(`✗ ${err.message || err}\n`));
+      process.exit(1);
+    }
+  };
+}
+
+const mcp = program
+  .command('mcp')
+  .description('MCP server: register Triss as a tool provider for Claude Code (and Codex soon)');
+
+mcp
+  .command('serve', { isDefault: true })
+  .description('Run the stdio MCP server. Claude Code starts this for you — no need to run it directly.')
+  .action(wrap(runMcpServe));
+
+mcp
+  .command('install')
+  .description('Register triss as MCP server for Claude Code (~/.claude.json) or Codex (~/.codex/config.toml)')
+  .option('-g, --global', 'install into the agent global config (default)')
+  .option('-l, --local', 'install into <cwd>/.mcp.json (claude only)')
+  .option('-t, --target <agent>', 'target agent (claude | codex | both); omit for an interactive prompt')
+  .option('--command <cmd>', 'override the executable name (default: triss)')
+  .option('--args <args>', "override args, space-separated (default: 'mcp serve')")
+  .action(wrap(runMcpInstall));
+
+mcp
+  .command('uninstall')
+  .description('Remove the triss MCP entry from the config')
+  .option('-g, --global', 'remove from the agent global config (default)')
+  .option('-l, --local', 'remove from <cwd>/.mcp.json (claude only)')
+  .option('-t, --target <agent>', 'target agent (claude | codex | both); omit for an interactive prompt')
+  .action(wrap(runMcpUninstall));
+
+mcp
+  .command('status')
+  .description('Show whether triss is registered and with what command')
+  .option('-g, --global', '(default) check the agent global config')
+  .option('-l, --local', 'check <cwd>/.mcp.json (claude only)')
+  .option('-t, --target <agent>', 'target agent (claude | codex | both). Default: both')
+  .action(wrap(runMcpStatus));
+
+// Plugin-style integrations (jira, linear, ...). See docs/extending.md.
+const integrations = await loadIntegrations();
+for (const manifest of integrations) {
+  const sub = program.command(manifest.name).description(manifest.description || manifest.name);
+  manifest.register(sub, { wrap });
+}
+
+await program.parseAsync(process.argv);

package/docs/configuration.md

@@ -0,0 +1,275 @@
+# Configuration
+
+Triss reads its credentials from `.env` files. **You should never need to
+create or edit those files by hand** — `triss config` handles everything.
+
+## TL;DR
+
+```bash
+triss config wizard         # interactive setup, prompts for every credential
+triss status                # verify what's loaded and from where
+```
+
+That is the entire happy path.
+
+---
+
+## Where credentials live
+
+Triss looks at two files, in this precedence order (highest first):
+
+| Scope     | Path                              | Purpose                                             |
+| --------- | --------------------------------- | --------------------------------------------------- |
+| `process.env` | exported in your shell        | Always wins. Use for CI / one-off overrides.        |
+| `local`   | `<project>/.triss.env`            | **Per-project** credentials. Overrides global here. |
+| `global`  | `~/.config/triss/.env`            | Default for every project.                          |
+
+**Same project, different Jira instances?** Put the org-wide DeepSeek key in
+the global file, and the project-specific Jira `ATLASSIAN_*` triple in
+`./.triss.env` for that repo. When you `cd` into another repo with its own
+`.triss.env`, Triss automatically uses *that* repo's credentials. The
+global Jira credentials (if any) keep working everywhere else.
+
+`.triss.env` is auto-`chmod 600` and auto-added to that project's
+`.gitignore` (if a `.gitignore` or `.git` exists). It is intentionally a
+different filename from the more common `.env` so it never collides with
+your application's own `.env`.
+
+---
+
+## `triss config` reference
+
+### `triss config wizard [target]`
+
+Interactive prompt-driven setup.
+
+When invoked **without a target**, the first question is **Standard vs
+Advanced**:
+
+| Mode      | What it asks                                                             | Use when                                  |
+| --------- | ------------------------------------------------------------------------ | ----------------------------------------- |
+| Standard  | API key + one worker-model name (written to both `flash` & `pro`)        | You just want it to work. Default.        |
+| Advanced  | Every variable for every integration, with confirm-before-each provider  | You need Jira/Linear, separate presets, custom base URL |
+
+```bash
+triss config wizard                       # asks Standard / Advanced first
+triss config wizard --standard            # straight into Standard
+triss config wizard --advanced            # straight into Advanced
+triss config wizard linear                # targeted: only Linear, no mode prompt
+triss config wizard linear --local        # targeted, project-local
+triss config wizard --advanced --force    # re-prompt for already-set keys
+```
+
+Behaviour:
+
+- Asks "Global or Project?" up front (skip with `--global` / `--local`).
+- Standard mode never asks about non-core integrations — run
+  `triss config wizard --advanced` (or a targeted invocation) later when
+  you actually need Jira/Linear.
+- Advanced mode asks "Configure jira? (y/N)" before each non-core
+  provider so you only walk through the ones you use.
+- Skips already-set values unless `--force`.
+- Masks secret inputs (anything matching `*KEY*`, `*TOKEN*`, `*SECRET*`,
+  `*PASS*`).
+- Uses every integration's `envVars` declaration — when you add a new
+  integration, the Advanced wizard picks up its variables for free.
+
+### `triss config set <KEY> [value]`
+
+Set a single variable.
+
+```bash
+triss config set DEEPSEEK_API_KEY                    # interactive masked prompt → global
+triss config set ATLASSIAN_API_TOKEN --local         # interactive → project
+triss config set DEEPSEEK_FLASH_MODEL deepseek-chat  # value as argument → global
+echo "$KEY" | triss config set LINEAR_API_KEY -      # read from stdin (CI-friendly)
+```
+
+### `triss config get <KEY>`
+
+```bash
+triss config get DEEPSEEK_API_KEY        # → "global  sk-d…294"  (masked)
+triss config get DEEPSEEK_API_KEY --local
+```
+
+Exits with code 1 if the key is missing.
+
+### `triss config list [--global|--local]`
+
+Lists every variable in each env file, with masking on secrets.
+
+### `triss config path [--global|--local]`
+
+Prints the absolute path(s) Triss will use, with `exists` / `missing`.
+
+### `triss config edit [--global|--local]`
+
+Opens the env file in `$VISUAL` → `$EDITOR` → `vi`. Without a flag, asks
+which file you mean.
+
+### `triss config unset <KEY> [--global|--local]`
+
+Removes a variable.
+
+---
+
+## Known credentials
+
+`triss config wizard` knows about:
+
+| Target     | Variables                                                                | Required                                  |
+| ---------- | ------------------------------------------------------------------------ | ----------------------------------------- |
+| `deepseek` | `DEEPSEEK_API_KEY`, `DEEPSEEK_BASE_URL`, `DEEPSEEK_FLASH_MODEL`, `DEEPSEEK_PRO_MODEL` | only `DEEPSEEK_API_KEY` is required |
+| `jira`     | `ATLASSIAN_BASE_URL`, `ATLASSIAN_EMAIL`, `ATLASSIAN_API_TOKEN`           | all three                                 |
+| `linear`   | `LINEAR_API_KEY`, `LINEAR_API_URL`                                       | only `LINEAR_API_KEY` is required         |
+
+When you add a new integration (see [extending.md](extending.md)), its
+`envVars` declaration is automatically picked up — no wizard changes needed.
+
+---
+
+## Recipes — common setups end-to-end
+
+### A. Single shared workspace (most users)
+
+One DeepSeek key, one Jira workspace, one Linear team. Everything global.
+
+```bash
+# install (once)
+curl -fsSL https://raw.githubusercontent.com/ayleen/triss-coworker/main/install.sh | bash
+
+# wizard — Standard mode auto-installs MCP + global CLAUDE.md
+triss config wizard --standard
+# (later, when you want Jira/Linear too)
+triss config wizard jira
+triss config wizard linear
+
+triss status          # verify everything is "ready"
+```
+
+Restart your Claude Code session. Done — every project sees the same
+credentials.
+
+### B. Different Jira instances per project
+
+You work for two clients with separate Atlassian Cloud orgs. Same
+DeepSeek key everywhere, but `~/work-acme/` should hit Acme's Jira and
+`~/work-beta/` should hit Beta's.
+
+```bash
+# global once — DeepSeek key + MCP server + global CLAUDE.md fallback
+triss config wizard --standard
+
+# per-project — Acme
+cd ~/work-acme
+triss config wizard jira --local
+#   → ATLASSIAN_BASE_URL=https://acme.atlassian.net
+#   → ATLASSIAN_EMAIL=you@acme.com
+#   → ATLASSIAN_API_TOKEN=ATATT-acme...
+#   writes <pwd>/.triss.env, chmod 600, adds to .gitignore.
+
+# per-project — Beta
+cd ~/work-beta
+triss config wizard jira --local
+#   → different Atlassian credentials, written to a separate .triss.env
+```
+
+What happens when you open Claude Code:
+
+| In `~/work-acme`  | MCP server reads `~/work-acme/.triss.env` → `triss_jira_*` tools call Acme's Jira  |
+| In `~/work-beta`  | MCP server reads `~/work-beta/.triss.env` → `triss_jira_*` tools call Beta's Jira  |
+| In any other dir  | No project `.triss.env` → no Jira tools at all (just core)                         |
+
+You don't reconfigure anything — the right credentials follow the
+working directory automatically.
+
+Verification: `triss status` from inside each project shows the
+`[local]` source tag next to the ATLASSIAN_* rows.
+
+### C. Personal DeepSeek key per project
+
+Want to charge a specific project to a separate billing account? Put
+its `DEEPSEEK_API_KEY` in `<project>/.triss.env`. The global key in
+`~/.config/triss/.env` keeps working everywhere else.
+
+```bash
+cd ~/special-project
+triss config set DEEPSEEK_API_KEY --local
+# (masked prompt → ./.triss.env)
+```
+
+### D. CI / scripts
+
+`process.env` always wins over `.env` files, so in CI you just export
+what you need:
+
+```yaml
+env:
+  DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}
+  ATLASSIAN_BASE_URL: ${{ vars.ATLASSIAN_BASE_URL }}
+  ATLASSIAN_EMAIL: ${{ vars.ATLASSIAN_EMAIL }}
+  ATLASSIAN_API_TOKEN: ${{ secrets.ATLASSIAN_API_TOKEN }}
+```
+
+`triss` commands then run unattended without needing any `.env` file.
+
+### E. Switching projects mid-session
+
+You added `.triss.env` to a project after Claude Code was already
+running there. As of v0.9.3, **no restart needed** — `.env` files are
+re-read on every `tools/list` request, so the next time the agent or
+`claude /mcp` lists tools, the new ones appear (or disappear).
+
+The only thing that requires a restart is the *initial* MCP-server
+registration — i.e. running `triss mcp install` for the first time.
+After that, credential changes are live.
+
+## Troubleshooting
+
+**"No DeepSeek API key found"** — `triss config wizard deepseek`.
+
+**Wrong credentials picked up** — `triss status` shows the source for each
+variable in `[global]` / `[local]` / `[env]` brackets. If you expected
+project-local to win and it didn't, check that the file is named exactly
+`.triss.env` (not `.env`) in your project root, and that you ran the
+command from that directory.
+
+**Switching organisations / Jira instances** — drop a `.triss.env` in the
+project root with the project-specific keys; nothing else needs to change.
+
+**Enabled an integration after `triss init`** — the agent's CLAUDE.md is
+re-rendered on every `triss init`, including only integrations whose
+required env vars are set. Run `triss init` again and your new
+integration's delegation rules will appear in the file.
+
+**Cost tracking** — every worker call appends to
+`~/.cache/triss/usage.jsonl`. Inspect with `triss usage`. To opt out
+entirely, set `TRISS_USAGE_LOG=0` before any call. To override the
+baked-in DeepSeek list prices (e.g. you point Triss at a different
+provider, or want the discounted rate), set
+`TRISS_PRICE_<MODEL>=<input_cache_miss>,<input_cache_hit>,<output>` in
+USD per token. Example: `TRISS_PRICE_DEEPSEEK_V4_PRO=4.35e-7,3.625e-9,8.7e-7`
+applies the 75% promotional pricing to the pro preset.
+
+**Claude Code integration step in the wizard** — split by mode:
+
+| Mode in `triss config wizard` | What happens at the end |
+| ----------------------------- | ----------------------- |
+| **Standard**                  | Installs both paths automatically (MCP server + global CLAUDE.md). No question asked — Standard's job is to make sensible defaults work. |
+| **Advanced**                  | Asks: 1) Both (default), 2) MCP only, 3) CLAUDE.md only, 4) Skip. |
+
+The two paths cooperate: MCP is the primary tool surface; CLAUDE.md
+acts as a fallback in case the MCP server can't load. Both can run
+side-by-side without conflict.
+
+Targeted invocations (`triss config wizard jira`) never touch the
+integration paths — credential changes happen with no side effects.
+Re-run the wizard to revisit; the install commands are idempotent.
+
+When MCP is registered, `triss init` automatically prepends a hint to
+the CLAUDE.md block that tells the agent to prefer the native MCP tools
+over the Bash invocations. So you don't get duplicate routing logic in
+the agent's prompt — just one path, with the other as fallback.
+
+**CI** — set the variables as environment variables directly. `process.env`
+wins over both files.