@bigstrider/transcodes-cli 0.9.0 → 0.11.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.
Files changed (3) hide show
  1. package/README.md +83 -30
  2. package/dist/index.js +29388 -3115
  3. package/package.json +13 -2
package/README.md CHANGED
@@ -1,59 +1,112 @@
1
- # @bigstrider/transcodes-cli
1
+ # `@bigstrider/transcodes-cli`
2
2
 
3
- Token manager for the **transcodes-guard** plugins (Claude Code / Codex / Cursor / Antigravity).
3
+ Human control plane for [transcodes-guard](https://github.com/transcodings/transcodes-guard).
4
+ Installs host plugins, signs you in with a browser (`transcodes login`), and
5
+ runs a small local dashboard. Plugins/hooks read the credential from
6
+ `~/.transcodes/config.json`.
4
7
 
5
- The plugins and their hooks authenticate to the Transcodes backend with a member MCP JWT. This CLI is the safe way to store that token: you paste it into your terminal, **never into the agent chat** (which would leak it into the transcript).
8
+ Permission checks default to **off**. Open the dashboard's **Permission** tab
9
+ and enable them explicitly; disabling them makes hooks skip backend evaluation.
6
10
 
7
11
  ## Install
8
12
 
9
13
  ```bash
10
- # no install needed — opens the dashboard
11
- npx @bigstrider/transcodes-cli
14
+ # macOS / Linux
15
+ curl -fsSL https://raw.githubusercontent.com/transcodings/transcodes-guard/prod/cli/install.sh | bash
12
16
 
13
- # or global
14
- npm install -g @bigstrider/transcodes-cli
15
- transcodes
17
+ # Windows (PowerShell)
18
+ irm https://raw.githubusercontent.com/transcodings/transcodes-guard/prod/cli/install.ps1 | iex
16
19
  ```
17
20
 
18
- Works the same on macOS, Linux, and Windows (Node ≥ 20).
21
+ Or: `npm install -g @bigstrider/transcodes-cli` (Node ≥ 20).
19
22
 
20
23
  ## Commands
21
24
 
22
25
  | Command | What it does |
23
26
  |---------|--------------|
24
- | `transcodes` | Opens the local dashboard (URL printed in the terminal; default port 3847, increments if busy) to paste, save, switch, label, or delete tokens (accepts `--port N` / `--no-open`). |
25
- | `transcodes set <token> -l <label>` | Validates the JWT and saves it (label required) to `~/.transcodes/config.json` (dir `0700`, file `0600`), making it active. |
26
- | `transcodes tokens` | Lists all saved tokens; the active one is marked with `*`. |
27
- | `transcodes status` | Shows the active token source and its expiry. |
28
- | `transcodes console` | Opens auth settings (passkeys, TOTP) for the active token in your browser. |
29
- | `transcodes reset` | Deletes all saved tokens. |
30
- | `transcodes policy refresh` | Force-refreshes the org policy bundle cache (same as MCP `refresh_rules`). |
31
- | `transcodes version` | Prints the installed `@bigstrider/transcodes-cli` npm version (also `--version`, `-V`). |
32
- | `transcodes help` | Shows the full command list and usage. |
33
-
34
- Command descriptions are defined once in `cli/src/commands.ts` (SSOT) and shared with the dashboard CLI tab.
27
+ | `transcodes` | Opens the local dashboard in the background (default port 3847; `--port N` / `--no-open`). |
28
+ | `transcodes stop` | Stops the background dashboard daemon. |
29
+ | `transcodes login` | Browser sign-in; saves the issued member credential as active. |
30
+ | `transcodes logout` | Removes the local credential (`reset` is an alias). |
31
+ | `transcodes status` | Shows whether a local credential is active and its expiry. |
32
+ | `transcodes console` | Opens auth settings (passkeys, TOTP) for the signed-in member. |
33
+ | `transcodes install` | Guided plugin install, then open the dashboard (sign in there). |
34
+ | `transcodes update` | Update installed plugins and this CLI. |
35
+ | `transcodes persona` | Create, inspect, edit, and delete local Persona bundles. |
36
+ | `transcodes version` | Prints the installed npm version. |
37
+ | `transcodes sync init` | Create `.transcodes/` SoT (rules + skills) in the current project. |
38
+ | `transcodes sync generate` | Generate Claude / Codex / Cursor / Antigravity configs from `.transcodes/`. |
39
+ | `transcodes sync add` | Scaffold a rule or skill under `.transcodes/`. |
40
+ | `transcodes help` | Full command list. |
41
+
42
+ Command descriptions are defined once in `cli/src/commands/` (SSOT) and shared with the dashboard CLI tab.
43
+
44
+ ### Persona automation
45
+
46
+ Persona sources are stored under `~/.transcodes/personas/<name>/`. The
47
+ `/transcodes` command (or `$transcodes` in Codex) can interview the user and
48
+ drive these JSON-friendly commands:
49
+
50
+ ```bash
51
+ transcodes persona list
52
+ transcodes persona create developer
53
+ transcodes persona read --persona developer --kind agent
54
+ transcodes persona save --persona developer --kind agent --content-file /tmp/instruction.md
55
+ transcodes persona save --persona developer --kind rule --name security --content-file /tmp/security.md
56
+ transcodes persona deploy --persona developer --project "/path/to/project" --targets claude,cursor
57
+ transcodes persona deploy --persona developer --global
58
+ ```
59
+
60
+ Run `transcodes persona help` for the complete command list.
61
+ `persona save` stores Markdown as provided. The `/transcodes` agent workflow
62
+ must follow its authoring and token rules before saving, but the CLI
63
+ intentionally does not validate or block the content.
64
+ `persona deploy` needs either an existing project folder plus target apps, or
65
+ `--global` to apply globally on this device. Global application makes the
66
+ Persona available in every project and session for the selected installed
67
+ Claude, Cursor, and Antigravity apps. Use it when the user does not know which
68
+ project or wants the Persona everywhere. The `/transcodes` agent workflow asks
69
+ for confirmation first.
70
+ The dashboard Persona panel remains available for manual review and Apply.
71
+
72
+ ### Project rules / skills sync
73
+
74
+ Keep a single source of truth under `.transcodes/`, then generate per-tool files:
75
+
76
+ ```bash
77
+ cd /path/to/your-project
78
+ transcodes sync init
79
+ # edit .transcodes/agents/agents.md, .transcodes/rules/*.md, .transcodes/skills/*/SKILL.md
80
+ transcodes sync generate -f rules,skills --simulate-skills
81
+ # omit -t → auto-detect installed Claude / Cursor / Codex / Antigravity (+ agentsmd)
82
+ # or pin: -t claudecode,cursor,agentsmd
83
+ ```
84
+
85
+ `transcodes sync` is a first-class CLI command under `cli/src/commands/transcodes/`
86
+ (same style as `login` / `install`). The generate engine is
87
+ `cli/src/commands/sync/`. Host-app detection for default targets is in
88
+ `cli/src/commands/transcodes/host-apps.ts`.
35
89
 
36
90
  ### Dashboard
37
91
 
38
92
  ```bash
39
93
  npx @bigstrider/transcodes-cli
94
+ # stop later:
95
+ npx @bigstrider/transcodes-cli stop
40
96
  ```
41
97
 
42
- Starts a small localhost server (127.0.0.1 only), opens your browser, and lets you save, switch, rename, or delete tokens without pasting them on the command line. Multiple tokens are kept in `~/.transcodes/config.json` under `token_list`, each with a label; the active one is stored as `token`.
98
+ Starts a localhost server (127.0.0.1 only) as a **background daemon**, opens
99
+ your browser, and returns the shell immediately. Pid/log live under
100
+ `~/.transcodes/state/dashboard.pid` and `dashboard.log`.
43
101
 
44
102
  Options:
45
103
 
46
- - `--port N` — bind to a specific port (default `3847`; increments if busy)
104
+ - `--port N` — prefer a specific port (default `3847`; increments if busy)
47
105
  - `--no-open` — do not open the browser automatically
48
106
 
49
- ## Token precedence
107
+ ## Credential store
50
108
 
51
- The plugins resolve the token from a single source (see `@transcodes-guard/core/stepup` `resolveToken()`):
109
+ Plugins resolve the credential from a single source (`resolveToken()`):
52
110
 
53
- 1. `~/.transcodes/config.json` — written by this CLI, the only source of truth
111
+ 1. `~/.transcodes/config.json` — written by `transcodes login`
54
112
  2. none → the hook fail-safes (blocks danger commands, cannot start step-up)
55
-
56
- ## Notes
57
-
58
- - **Windows security**: the `0600` mode is a POSIX concept and is largely ignored on Windows. The file still lives under your user profile (`C:\Users\<you>\.transcodes\`) and is user-scoped by default. A hardware-backed OS keychain is not yet implemented.
59
- - The token never passes through the agent chat — this CLI writes the file directly.