@bigstrider/transcodes-cli 0.10.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 +75 -50
  2. package/dist/index.js +29222 -3784
  3. package/package.json +12 -2
package/README.md CHANGED
@@ -1,61 +1,91 @@
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
- One line — no need to have `npm` (or even Node) already. The script installs
10
- an LTS Node if it is missing, then puts `transcodes` on your PATH.
11
-
12
13
  ```bash
13
14
  # macOS / Linux
14
- curl -fsSL https://raw.githubusercontent.com/transcodings/transcodes-guard/prod/cli/install.sh | bash && transcodes install
15
- ```
15
+ curl -fsSL https://raw.githubusercontent.com/transcodings/transcodes-guard/prod/cli/install.sh | bash
16
16
 
17
- ```powershell
18
17
  # Windows (PowerShell)
19
- irm https://raw.githubusercontent.com/transcodings/transcodes-guard/prod/cli/install.ps1 | iex; transcodes install
18
+ irm https://raw.githubusercontent.com/transcodings/transcodes-guard/prod/cli/install.ps1 | iex
20
19
  ```
21
20
 
22
- > Windows: if script execution is blocked by policy, prefix it once (this only
23
- > affects the current session):
24
- >
25
- > ```powershell
26
- > Set-ExecutionPolicy Bypass -Scope Process -Force; irm https://raw.githubusercontent.com/transcodings/transcodes-guard/prod/cli/install.ps1 | iex
27
- > ```
21
+ Or: `npm install -g @bigstrider/transcodes-cli` (Node ≥ 20).
28
22
 
29
- Already have Node ≥ 20? The plain npm route still works everywhere:
23
+ ## Commands
30
24
 
31
- ```bash
32
- # no install needed — opens the dashboard
33
- npx @bigstrider/transcodes-cli
25
+ | Command | What it does |
26
+ |---------|--------------|
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:
34
49
 
35
- # or global
36
- npm install -g @bigstrider/transcodes-cli
37
- transcodes
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
38
58
  ```
39
59
 
40
- Node ≥ 20 is required (the CLI and the guard hooks both run on Node); the
41
- bootstrap scripts above install it for you if needed.
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.
42
71
 
43
- ## Commands
72
+ ### Project rules / skills sync
44
73
 
45
- | Command | What it does |
46
- |---------|--------------|
47
- | `transcodes` | Opens the local dashboard in the background (restarts daemon from this CLI binary; default port 3847; `--port N` / `--no-open`). Shell returns immediately. |
48
- | `transcodes stop` | Stops the background dashboard daemon. |
49
- | `transcodes set <token> -l <label>` | Validates the JWT and saves it (label required) to `~/.transcodes/config.json` (dir `0700`, file `0600`), making it active. |
50
- | `transcodes tokens` | Lists all saved tokens; the active one is marked with `*`. |
51
- | `transcodes status` | Shows the active token source and its expiry. |
52
- | `transcodes console` | Opens auth settings (passkeys, TOTP) for the active token in your browser. |
53
- | `transcodes reset` | Deletes all saved tokens. |
54
- | `transcodes policy refresh` | Force-refreshes the org policy bundle cache (same as MCP `refresh_rules`). |
55
- | `transcodes version` | Prints the installed `@bigstrider/transcodes-cli` npm version (also `--version`, `-V`). |
56
- | `transcodes help` | Shows the full command list and usage. |
74
+ Keep a single source of truth under `.transcodes/`, then generate per-tool files:
57
75
 
58
- Command descriptions are defined once in `cli/src/commands.ts` (SSOT) and shared with the dashboard CLI tab.
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`.
59
89
 
60
90
  ### Dashboard
61
91
 
@@ -65,23 +95,18 @@ npx @bigstrider/transcodes-cli
65
95
  npx @bigstrider/transcodes-cli stop
66
96
  ```
67
97
 
68
- Starts a small localhost server (127.0.0.1 only) as a **background daemon**, opens your browser, and returns the shell immediately. Each `transcodes` run restarts the daemon from the CLI binary you just invoked (so a local `npm run build` is picked up). Stop it with `transcodes stop`.
69
-
70
- Multiple tokens are kept in `~/.transcodes/config.json` under `token_list`, each with a label; the active one is stored as `token`. Pid/log live under `~/.transcodes/state/dashboard.pid` and `dashboard.log`.
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`.
71
101
 
72
102
  Options:
73
103
 
74
104
  - `--port N` — prefer a specific port (default `3847`; increments if busy)
75
105
  - `--no-open` — do not open the browser automatically
76
106
 
77
- ## Token precedence
107
+ ## Credential store
78
108
 
79
- 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()`):
80
110
 
81
- 1. `~/.transcodes/config.json` — written by this CLI, the only source of truth
111
+ 1. `~/.transcodes/config.json` — written by `transcodes login`
82
112
  2. none → the hook fail-safes (blocks danger commands, cannot start step-up)
83
-
84
- ## Notes
85
-
86
- - **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.
87
- - The token never passes through the agent chat — this CLI writes the file directly.