@machinal/mcp 0.4.3 → 0.4.4

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/README.md CHANGED
@@ -8,11 +8,34 @@ See the repository's [testing guide](../../docs/TESTING.md) for source-package a
8
8
 
9
9
  Requires **Node.js 22.13+ (22.x) or 24+** and an installed agent client. **Machinal Server** needs only a Machinal key with account/API access: its official endpoint is selected automatically, with no address question and no Docker/provider key on the client. **Custom server** is the advanced option for your own API URL. Independent local needs Docker/Compose v2, this version's source checkout, and your OpenRouter key/model settings: **no Machinal account, subscription, credits or PocketBase**. The npm package does not bundle the Go backend or guess an unpublished container image.
10
10
 
11
- **Server: one Machinal key. Local: your OpenRouter key.** Hidden entry and opt-in Windows Credential Manager storage are supported for server keys. All three adapters can read the saved Windows key without a launcher. On macOS/Linux use your client environment/secret manager or optional keyed launcher. No key belongs in chat or command arguments.
11
+ **Server: one Machinal key. Local: your OpenRouter key.** Hidden entry and opt-in persistent storage are supported: Windows Credential Manager on Windows; a private plaintext credentials file on Linux. All three stdio adapters read the saved key without a launcher. macOS retains environment/hidden-entry behavior. No key belongs in chat or command arguments.
12
+
13
+ ### Short commands (0.4.4)
14
+
15
+ Install version 0.4.4 or later for these commands. From a source checkout, use `node packages/mcp-installer/bin/machinal-mcp.mjs <command>`:
16
+
17
+ ```sh
18
+ npx @machinal/mcp set-key # Hidden entry, verify, then confirm saving
19
+ npx @machinal/mcp getcredit # Live balance; no spending
20
+ npx @machinal/mcp place # Processing, source folder and download locations
21
+ npx @machinal/mcp place --uploads /home/me/Media --downloads /home/me/Videos
22
+ npx @machinal/mcp local status
23
+ npx @machinal/mcp local install --docker-dir /path/to/machinal
24
+ ```
25
+
26
+ `npm install -g @machinal/mcp` also provides `machinal set-key`, `machinal getcredit`, `machinal place`, `machinal local status` and `machinal local install`. The existing `machinal-mcp` binary and `key set` / `key delete` remain compatible. `npx machinal` would resolve a different npm package; use `npx @machinal/mcp` (or `npx --package @machinal/mcp machinal`) instead.
27
+
28
+ Linux saves a key only after explicit approval to `$XDG_CONFIG_HOME/machinal/credentials.json`, or `~/.config/machinal/credentials.json`. Directory mode is `0700`, file mode `0600`; the file is **not encrypted** and other processes running as that user can read it. Saves are atomic, do not create secret backups, and never fall back to a project file. Incorrect ownership, exposed permissions, symlinks, corrupt data or an unreadable file produce a sanitized diagnostic, not a missing-key assumption. The CLI, stable adapter and Linux OpenCode companion use the same location. `MACHINAL_API_KEY` (then legacy `DIRECTION_API_KEY`) takes precedence on Linux; remove a stale environment override to use the saved replacement.
29
+
30
+ `set-key` uses the last configured hosted endpoint (or the official service for a new setup) and verifies before saving. `key set` without `--url` retains its legacy format-only behavior. Linux OpenCode's `replace` directs the **user** to hidden terminal entry; it never requests a key through chat or launches Windows UI. Changes are picked up automatically or with `machinal_connection reconnect`.
31
+
32
+ `place` stores only host-side folder preferences in `machinal/config.json`, separately from credentials. Uploads still go to the named project's volume; the source folder is a suggestion, not automatic browsing or transfer permission. Native OpenCode project downloads prefer an explicit destination, then this host's saved folder, then the API's saved preference. Internet downloads still require an explicit destination. Setting a folder transfers nothing and does not change the server's preferences.
33
+
34
+ Local mode detects a saved profile and reuses a running backend. With permission it builds missing Docker images from a detected checkout, or starts installed images without rebuilding. `--yes` alone does not authorize Docker startup; use `--start-docker` for unattended installation. Docker/Compose and a source checkout are prerequisites: no Engine installation with administrator privileges, guessed public image or private source publication is performed. Choosing Server never inspects or installs Docker.
12
35
 
13
36
  **Migration compatibility:** existing `dal_…` keys, `DIRECTION_API_KEY` / `DIRECTION_API_ORIGIN` environment variables, and the previous Windows Credential Manager entry continue to work. New setups use `mach_…`, `MACHINAL_API_KEY` / `MACHINAL_API_ORIGIN`, and `Machinal/mcp.MACHINAL_API_KEY`; when both environment names are set, `MACHINAL_API_KEY` takes precedence. New keys are issued with the `mach_` prefix.
14
37
 
15
- **Version 0.4.3:** use the pinned commands below to install this release from the `@machinal` scope:
38
+ **Version 0.4.4:** use the pinned commands below to install this release from the `@machinal` scope:
16
39
 
17
40
  This release adds native approved client-file uploads and language-independent video preparation. `machinal_prepare_video` loads actual production skills including cinema; scene compilation/final rendering are guarded until that session context is loaded. No keyword classifier, extra model call or automatic spending is introduced.
18
41
 
@@ -21,14 +44,14 @@ OpenCode compatibility: production startup accepts the V2 skill-list response (`
21
44
  ```sh
22
45
  npx @machinal/mcp setup
23
46
  # Machinal Server: no URL entry, only your Machinal key:
24
- npx --yes @machinal/mcp@0.4.3 setup --client opencode --mode server
25
- npx --yes @machinal/mcp@0.4.3 setup --client codex --mode server
26
- npx --yes @machinal/mcp@0.4.3 setup --client claude --scope global --mode server
47
+ npx --yes @machinal/mcp@0.4.4 setup --client opencode --mode server
48
+ npx --yes @machinal/mcp@0.4.4 setup --client codex --mode server
49
+ npx --yes @machinal/mcp@0.4.4 setup --client claude --scope global --mode server
27
50
  # Independent local; the wizard asks for OpenRouter and model IDs:
28
- npx --yes @machinal/mcp@0.4.3 setup --client codex --mode local --docker-dir /path/to/machinal
29
- npx --yes @machinal/mcp@0.4.3 setup --client claude --mode local --docker-dir /path/to/machinal
51
+ npx --yes @machinal/mcp@0.4.4 setup --client codex --mode local --docker-dir /path/to/machinal
52
+ npx --yes @machinal/mcp@0.4.4 setup --client claude --mode local --docker-dir /path/to/machinal
30
53
  # Your own deployment, explicitly selected:
31
- npx --yes @machinal/mcp@0.4.3 setup --client opencode --mode custom --url https://YOUR-API/mcp
54
+ npx --yes @machinal/mcp@0.4.4 setup --client opencode --mode custom --url https://YOUR-API/mcp
32
55
  ```
33
56
 
34
57
  The wizard asks for:
@@ -38,7 +61,7 @@ The wizard asks for:
38
61
  3. **Machinal Server**, **Local**, or **Custom server (advanced)**. Machinal Server automatically uses `https://api.machinal.app/mcp` and never asks for an address or starts Docker. Local builds an independent backend with loopback host publishing and separate volumes; its default is `http://127.0.0.1:8080/mcp`. Custom server asks for your own API URL, **not the frontend URL**, without offering localhost as a guessed hosted default.
39
62
  4. Whether to install bundled editing, YAML recipe, scene and credit-awareness skills, and a default editing style.
40
63
  5. **Machinal Server:** hidden Machinal key, reuse environment/saved key, or login later (`--defer-login`). Create keys at <https://machinal.app/api-keys>; custom deployments use their own account website. **Local:** hidden `OPENROUTER_API_KEY`, required `OPENROUTER_MODEL`, optional scene/transcription model IDs, source checkout and explicit Docker approval. A device token is generated automatically; no local Machinal key is requested.
41
- 6. Windows Server mode: optionally remember a verified key in Credential Manager (default: no).
64
+ 6. Server mode on Windows/Linux: optionally remember a verified key in the platform's storage (default: no; Linux explicitly identifies plaintext storage).
42
65
  7. Optional client launch. `--no-launch` works even when login is deferred.
43
66
 
44
67
  Setup preserves unrelated settings, backs up changed files and installs optional skills. Missing login/offline Server still permits adapter installation, with an explicit **unverified** service status. Verification uses initialization, tool discovery and read-only billing mode, never generation, rendering, provider calls or credit purchases. An API probe is never reported as a running client connection.
@@ -67,8 +90,8 @@ The following bullets describe **advanced direct-HTTP compatibility** (`--transp
67
90
  - It checks Docker/Compose, refuses remote Docker contexts, requires an existing `api/.env`, and inspects containers/images. With approval, it reuses existing images or builds missing ones, then runs the checkout's `api` and `scene-renderer` services with readiness waiting. Build/start may download base images, use disk/CPU, create persistent volumes and expose port 8080 according to the checkout's Compose configuration. Readiness is not proof of API authentication or provider credit.
68
91
  - **`--yes` alone never authorizes build/start.** Interactive confirmation defaults to no; unattended use needs explicit `--start-docker`. No Docker Engine installation, context switching, secret creation, volume deletion, or registry publication happens automatically. A missing Docker executable links to <https://docs.docker.com/get-started/get-docker/>. Nonstandard local ports require a deployment started by the user.
69
92
  - Container/build output is not dumped into the terminal because it may include secrets. Failures suggest checks for the daemon, context, ports, disk and network. Services keep running after setup, even if later MCP verification fails; manage them from the reported checkout. No destructive automatic rollback is performed.
70
- - The terminal interface follows your terminal's background and text colors. Cyan marks only the selected option; amber/red mark warning/error labels, not entire paragraphs. Short menus show up to five choices and collapse to a one-line answer. Completed key prompts show `[hidden]`, not the key or its length; visibility toggling is disabled. `NO_COLOR` (including an empty value) and `TERM=dumb` disable theme colors. Piped output stays plain.
71
- - Interactive setup finishes with one compact verification/configuration/credit summary. Use `setup --verbose` for full authentication explanations, credit breakdowns, reset dates and configured rates. Unattended setup retains the detailed plain-text report. Important compatibility, billing, low-balance and backup warnings are never hidden. Backup details remain grouped into **one summary**, with file count, root/config path, sibling filename pattern and restoration instructions rather than a line per skill.
93
+ - The terminal interface follows your terminal's background and neutral text color (white on a dark terminal), with purple headings, prompt marks and selected options. Amber/red mark warning/error labels, not paragraphs. Menus show at most five choices and collapse to one answer. Completed key prompts show `[hidden]`, not the key or its length; visibility toggling is disabled. `NO_COLOR` (including an empty value), `TERM=dumb` and piped output disable theme colors.
94
+ - Default stdio setup finishes with a compact verification/configuration/credit summary, including unattended output. Use `setup --verbose` for full credit breakdowns and diagnostics; `--help --verbose` shows all flags. Important compatibility, billing, low-balance and backup warnings remain visible. Advanced direct-HTTP compatibility retains its detailed unattended report. Backup details remain grouped into **one summary**, rather than a line per skill.
72
95
 
73
96
  From this repository (no npm publication required):
74
97
 
@@ -87,7 +110,7 @@ node packages/mcp-installer/bin/machinal-mcp.mjs setup --client opencode --mode
87
110
 
88
111
  This section describes Server mode. Independent local returns `mode:local` / `machinalCreditsRequired:false`, not a wallet: there are no hosted credit thresholds or render tariffs to check. Direct provider charges still need user permission.
89
112
 
90
- Setup calls only MCP initialization, tool discovery and the read-only `get_credits` tool. It shows a concise balance and billing notice; `--verbose` or unattended setup also shows the breakdown, next reset and configured pricing. Credits are charged after actual usage, not reserved for current work. Pending provider costs are informational, not a wallet lock. A brief low-balance warning appears below 30 credits; estimates are approximate. No wallet values are stored in skill files or configuration.
113
+ Setup calls only MCP initialization, tool discovery and the read-only `get_credits` tool. It shows a concise balance and billing notice; `--verbose` also shows the breakdown, next reset and configured pricing. Credits are charged after actual usage, not reserved for current work. Pending provider costs are informational, not a wallet lock. A brief low-balance warning appears below 30 credits; estimates are approximate. No wallet values are stored in skill files or configuration.
91
114
 
92
115
  Older APIs without `get_credits`, unavailable ledgers and malformed balances produce a clear “unavailable” warning, not a fabricated zero. Authentication loss aborts setup. An unavailable wallet does not prevent free recipe preparation, but the agent is instructed to verify credits before submitting paid work. AI charges are not known exactly in advance, and a shared wallet delta is not an exact per-job charge.
93
116
 
@@ -126,17 +149,23 @@ Use the current local source with `node packages/mcp-installer/bin/machinal-mcp.
126
149
 
127
150
  The API now exposes `get_workflow_preferences` and approved `set_workflow_preferences`. They persist per application key: `style`, `sceneMode` (`auto`, `2d`, `3d`), `imagePolicy` (`auto`, `prefer-images`, `procedural-only`) and `captionMaxWords` (default 4). Omitted fields are preserved. Current briefs override defaults; preferences never grant media access or spending permission. Three.js/font/image contracts are available through `get_editing_reference(topic: scene-runtime)` and the bundled scene runtime reference.
128
151
 
129
- Connection settings remain separate: rerun setup with `--mode server|local` and the correct `--url`. Server keys come from environment, Windows Credential Manager or hidden entry; independent local uses its own provider profile/device token. Neither connection proves upstream provider credit. Rebuild/reconnect for new API tools.
152
+ Connection settings remain separate: rerun setup with `--mode server|local` and the correct `--url`. Server keys come from environment, platform storage or hidden entry; independent local uses its own provider profile/device token. Neither connection proves upstream provider credit. Rebuild/reconnect for new API tools.
130
153
 
131
154
  ### Later sessions
132
155
 
133
- For OpenCode on Windows, **start OpenCode normally**. The integration reads the same saved machinal key automatically and supplies it only to the exact MCP name/endpoint approved during setup. Project overrides cannot silently redirect that saved key to another API origin. Configuration contains the plugin registration and trusted endpoint, never the key. Source checkouts reference the local plugin directory; published npm installations register the matching pinned package version rather than an expendable `npx` cache path.
156
+ For OpenCode on Windows or Linux, **start OpenCode normally**. The integration reads the same saved machinal key automatically and supplies it only to the exact MCP name/endpoint approved during setup. Project overrides cannot silently redirect that saved key to another API origin. Configuration contains the plugin registration and trusted endpoint, never the key. Source checkouts reference the local plugin directory; published npm installations register the matching pinned package version rather than an expendable `npx` cache path.
157
+
158
+ ### Synchronized OpenCode upgrades (0.4.4)
159
+
160
+ Rerunning stdio setup from an updated package synchronizes its companion version and managed runtime in existing applicable global, ancestor and project configs, including `.opencode` configs. It does not recursively scan other projects. Matching local-development/npm duplicate entries are consolidated, while unrelated plugins, endpoints, routing options and server settings remain intact. Each changed file gets an exact backup; invalid configs, conflicting duplicate options and unapproved command overrides stop the upgrade with an actionable diagnostic. A version-only managed-runtime change does not require `--replace`; endpoint or other server changes still do.
161
+
162
+ When OpenCode loads an updated companion package, it also prepares that package's private runtime and substitutes it in memory **only after** matching the exact approved MCP command. This covers package-manager/plugin updates without a separate setup run; it does not change endpoints, write credentials, fetch another release or retry work. `machinal_connection status` includes the loaded package version, and a configuration mismatch is explicitly distinguished from a rejected API key. These changes require 0.4.4 or later.
134
163
 
135
164
  The agent has a local **`machinal_connection`** tool even when the remote API is disconnected:
136
165
 
137
- - **`status`** discovers approved MCP names/endpoints, actual connection states and credential diagnostics, including the exact Windows target `Machinal/mcp.MACHINAL_API_KEY` (service `Machinal/mcp`, account `MACHINAL_API_KEY`), never the key. Missing, redirected or incompatible MCP configurations are reported separately; keys are not sent to them.
166
+ - **`status`** discovers approved MCP names/endpoints, actual connection states and credential diagnostics: Linux reports the private file path; Windows reports target `Machinal/mcp.MACHINAL_API_KEY` (service `Machinal/mcp`, account `MACHINAL_API_KEY`), never the key. Missing, redirected or incompatible MCP configurations are reported separately; keys are not sent to them.
138
167
  - **`reconnect`** reloads the one saved key, checks access and reconnects the existing MCP without restarting OpenCode. Transient failures retry; a network or subscription failure is not a reason to generate more keys.
139
- - **`replace`** opens a native Windows window with masked entry, a direct <https://direction.al/api-keys> link, **Use saved key**, **Verify and connect**, and Cancel. Saving a replacement requires a separate unchecked-by-default consent checkbox. Verification happens before any overwrite. Cancellation or rejection preserves the previous saved key. No credential is passed through chat, tool inputs, command arguments, plaintext files, or logs.
168
+ - **`replace`** on Windows opens a native window with masked entry, a direct <https://machinal.app/api-keys> link, **Use saved key**, **Verify and connect**, and Cancel. Saving requires a separate unchecked-by-default consent checkbox. Verification precedes overwrite; cancellation/rejection preserves the saved key. Linux returns terminal instructions for `set-key` instead. Neither platform passes a key through chat, tool inputs, command arguments or logs; only Linux explicitly persists it to its private plaintext file.
140
169
 
141
170
  Only one key is stored per Windows user and reused across the configured projects/clients. A replacement is read by running automatic integrations without a separate relaunch. The plugin uses the saved key before an incidental environment value; the optional legacy launcher marks its explicitly chosen environment key so `--session-key` and intentional per-session choices still work. Secure entry requires an interactive Windows desktop; it is not promised for a headless/remote service.
142
171
 
@@ -224,7 +253,7 @@ npx @machinal/mcp launch claude
224
253
  npx @machinal/mcp launch codex
225
254
  ```
226
255
 
227
- `launch` checks sources in order: `MACHINAL_API_KEY`, the saved Windows credential, then hidden entry. Interactive sessions ask whether to keep, replace, or create a key; unattended sessions retain automatic first-available selection. Keeping a saved key does not require typing it again. Newly supplied keys can optionally be remembered on Windows. It launches the already installed client; it does not install that client or modify configuration. Optional client arguments follow `--`:
256
+ `launch` checks sources in order: `MACHINAL_API_KEY`, the platform's saved credential, then hidden entry. Interactive sessions ask whether to keep, replace, or create a key; unattended sessions retain automatic first-available selection. Keeping a saved key does not require typing it again. New keys can optionally be remembered on Windows/Linux. It launches the already installed client; it does not install that client or modify configuration. Optional client arguments follow `--`:
228
257
 
229
258
  ```sh
230
259
  npx @machinal/mcp launch codex -- --help
@@ -234,7 +263,9 @@ OpenCode launches with **`--standalone`** so its private server inherits the key
234
263
 
235
264
  The setup API probe alone never proves a running client connection. On Windows the installed integration lets the shared OpenCode service authenticate directly from the vault; inspect `machinal_connection(status)` or the MCP panel for the actual state. Without that integration, legacy environment-based setups still need a client/server started with the verified key.
236
265
 
237
- ### Save, replace, or delete a key on Windows
266
+ <a id="save-replace-or-delete-a-key-on-windows"></a>
267
+
268
+ ### Save, replace, or delete a key on Windows or Linux
238
269
 
239
270
  ```sh
240
271
  npx @machinal/mcp key set
@@ -252,13 +283,13 @@ npx @machinal/mcp key delete --yes
252
283
  - An existing **`MACHINAL_API_KEY` takes precedence**, including after replacement/deletion. Unset it if you want subsequent launcher sessions to use the saved credential.
253
284
  - **`--session-key`** on `setup` or `launch` bypasses the vault entirely and suppresses the save offer. It still accepts `MACHINAL_API_KEY` or hidden entry. Without saving, the key is kept only for the current installer/client processes.
254
285
 
255
- Credential Manager is accessed through the optional, pinned `@napi-rs/keyring` native binding. No key is sent through `cmdkey`, subprocess arguments, or plaintext files. If the binding/vault is unavailable, interactive setup/launch offers hidden entry; unattended reads fail with recovery guidance, and `--session-key` or an environment-supplied key still works. A failed optional save is reported and session-only use remains possible. macOS/Linux retain environment/hidden-entry behavior; these commands do not write a plaintext fallback there.
286
+ On Windows, Credential Manager is accessed through the optional, pinned `@napi-rs/keyring` native binding; there is no plaintext fallback. Linux deliberately uses the private file described above, without D-Bus/keyring dependencies. macOS retains environment/hidden-entry behavior. A failed optional save is reported; no alternate storage is silently used.
256
287
 
257
288
  Windows protects stored credentials at rest, but this is **not isolation from applications running under the same Windows account**, an administrator, or a compromised client. Automatic OpenCode authentication holds the key in its server memory. Legacy launcher sessions also pass it in the child's environment. Normal OpenCode startup reads the vault through the installed integration, not through shell initialization.
258
289
 
259
290
  ### Key handling
260
291
 
261
- - **Server application keys** are never written to plaintext files, client arguments or output. Persistence is opt-in through Windows Credential Manager. Independent local provider/device secrets are deliberately stored in a private external Docker profile, never client config or the npm tarball.
292
+ - **Server application keys** never enter client configuration, arguments or output. Opt-in persistence uses Windows Credential Manager or a private **plaintext** file on Linux. Independent local provider/device secrets use a separate private Docker profile, never client config or the npm tarball.
262
293
  - Keys are kept in installer memory and passed in the launched child's environment. As with other environment-held secrets, the client and its subprocesses can access them. Use a dedicated, revocable key for each trusted client.
263
294
  - `npx` cannot change its parent shell's environment. If you decline immediate launch, the key you typed does **not** become available to clients started elsewhere. If saved, `launch` reads it from Credential Manager next time; otherwise supply it again or use your own environment/secret manager.
264
295
  - Do not pass a key through CLI arguments, paste it in chat, or put it in your shell history. There is deliberately no `--api-key` option.
@@ -356,7 +387,7 @@ Test the npm executable/tarball path without publishing:
356
387
  ```sh
357
388
  npm pack --dry-run
358
389
  npm pack
359
- npx --yes --package ./machinal-mcp-0.4.3.tgz machinal-mcp --help
390
+ npx --yes --package ./machinal-mcp-0.4.4.tgz machinal-mcp --help
360
391
  ```
361
392
 
362
393
  The publish allowlist includes only selected `bin/*.mjs`, runtime/plugin source, portable skills, package metadata and this README. Package smoke tests reject project configs, nested agent installs, `.env`, media and old archives. No tests, local preferences or credentials are packaged.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@machinal/mcp",
3
- "version": "0.4.3",
3
+ "version": "0.4.4",
4
4
  "description": "Resilient Machinal MCP setup for Codex, Claude Code and OpenCode: independent local or hosted server",
5
5
  "type": "module",
6
6
  "exports": {
@@ -11,7 +11,8 @@
11
11
  "node": "^22.13.0 || >=24.0.0"
12
12
  },
13
13
  "bin": {
14
- "machinal-mcp": "bin/machinal-mcp.mjs"
14
+ "machinal-mcp": "bin/machinal-mcp.mjs",
15
+ "machinal": "bin/machinal-mcp.mjs"
15
16
  },
16
17
  "files": [
17
18
  "bin/*.mjs",
@@ -27,6 +27,6 @@ Before authoring a new video, use `machinal-editing` and `get_editing_reference(
27
27
  8. Enumerate pending provider actions, check live credits and get explicit source-use/spending authorization before `generate_assets`/`render_video(userApproved:true)`. Keep returned resolved assets/documents, then finish/revalidate treatments on actual track IDs after generation. Inspect jobs/media before new paid work and reuse stable exact-operation idempotency keys.
28
28
  9. After completion and receiving approval, `get_video_result(delivery:link,userApproved:true)` returns an opaque one-hour application download link: give the requested clickable link/expiry, not raw S3 credentials or a local path. Only an explicitly requested client-local file uses `delivery:local` and approved download preferences; ask if unset, never overwrite and verify the full file. The Docker/server volume is not the client's filesystem and the server never writes to that client directory. Never attach the application key to links/redirects, print underlying signed S3 URLs or embed them in visible commands. Permission flags report an actual user reply; never self-approve.
29
29
 
30
- `save_project` is separate: it needs the complete editor state and current version, not YAML. Preserve all fields and reconcile 409 conflicts. Keep API keys, authorization headers and private credential paths out of recipes, filenames, output and chat.
30
+ A project means the saved editable timeline plus all used assets, not a JSON/YAML download or just a populated Media Bin. Successful generation/final rendering on the updated API publish the resolved edit into an empty/media-only or untouched prepared project; manual edits are preserved and can be explicitly replaced using Open prepared/rendered timeline in the editor. Verify saved tracks/clips, audio, exact captions, treatments and pinned asset references with `get_project` before claiming project completion. Do not regenerate/rerender merely to save/reopen an edit. `save_project` still needs complete editor state and the current version, never YAML; preserve unrelated fields and reconcile 409 conflicts. Keep API keys, authorization headers and private credential paths out of recipes, filenames, output and chat.
31
31
 
32
32
  Keep generation, scene compilation, text preparation and rendering in Directional. Do not build local Python/FFmpeg pipelines or HTTP bridges. For unchanged continuation use sourceJobId; use get_job_result once for resolved recipeYaml when editing is needed. Prefer wait_for_job(timeoutSeconds:120), not repetitive progress lookups or sleep scripts. For left-edge titles use anchor:left and align:left; x/y are design pixels, not percentages. Preserve the approved final delivery separately from processing-location preferences. Do not promise music generation when capabilities say unsupported. Scene YAML prompts are concrete storyboards, not generic headings or vague CSS: specify subject/action, medium, composition/depth, palette/light, exact copy and local reveal/action/hold/exit. Use visualMode:3d with real SceneThree for requested spatial scenes. Never put AI-production labels/disclaimers/watermarks on screen, including in image prompts or textures.
@@ -42,6 +42,8 @@ An asset identifies `{id, file, version, kind, duration, width?, height?, hasAud
42
42
 
43
43
  `snapshot` has `{revision, tracks, effects, transitions, textItems, selectedIds}` and captures the **compiler timeline**. `get_project` returns editor state, not automatically a ready compiler snapshot; obtain/construct an appropriate current snapshot rather than treating `state.timeline` as this object verbatim. `save_project` takes full editor state and its numeric current project `version`, never raw recipe YAML. `preparedText` is renderer-produced text preparation; do not fabricate its hashes/images.
44
44
 
45
+ A project is the saved **editable timeline and its source assets**, not a recipe download. Successful generation and final rendering publish their resolved composition into that owned project's editor state when it is empty/media-only or still matches the untouched previous preparation. Tracks/clips, narration, exact captions and resolved job IDs, effects, transitions, output settings and pinned assets are retained. Manual edits (including intentionally cleared documents) are not silently replaced; **Open prepared timeline / Open rendered timeline** in Projects explicitly restores a retained edit with confirmation and keeps the project's media. `get_project` also repairs legacy media-only states from retained snapshots without paid work. Check the saved project after production; a local `.edit.yaml` checkpoint alone is not project delivery. Free validation/compilation is not a save operation, and no recipe file substitutes for the editor timeline.
46
+
45
47
  ## Sequence and clips
46
48
 
47
49
  `sequence.each`: `take: {from, duration}`; duration is **timeline** duration. A rate of 2 consumes twice that much source. `rate` is 0.25–4. `source_audio` is `keep|remove` (default keep). `volume` is 0–200 **percent**, not 0–1 gain. `look` and `motion` are exact catalog IDs. A clip must have at least 100ms timeline time and fit the real source (images can be held without a finite source duration).
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: machinal-support
3
- description: Discover and troubleshoot machinal MCP, missing tools, disconnected servers, authentication and saved API keys in Windows Credential Manager. Use immediately when machinal tools are unavailable or a connection/key fails; recover the existing integration before asking for setup or a replacement key.
3
+ description: Discover and troubleshoot machinal MCP, missing tools, disconnected servers, authentication and saved keys on Windows/Linux. Use immediately when machinal tools are unavailable or a connection/key fails; recover the existing integration before asking for setup or a replacement key.
4
4
  ---
5
5
 
6
6
  # MCP discovery and credential recovery
@@ -20,6 +20,10 @@ The local `machinal_connection` tool is independent of the remote MCP and remain
20
20
 
21
21
  ## Exact saved-key location
22
22
 
23
+ On **Linux**, the integration and stdio adapter read `$XDG_CONFIG_HOME/machinal/credentials.json`, or `~/.config/machinal/credentials.json`. This is an explicitly approved plaintext file, mode `0600` inside a `0700` directory, not project configuration. `MACHINAL_API_KEY` / legacy `DIRECTION_API_KEY` take precedence. Diagnostics report the selected path/source without revealing the value. Do not read the file or dump environment values through agent tools. For a missing/invalid/rejected key, `replace` returns `terminal-key-required` / `nextAction:set-key`: ask the user to run `npx @machinal/mcp set-key` in their own terminal, with hidden entry and verification before saving. Reconnect afterward; no Windows window or key in chat. Unreadable files/unsafe permissions are not missing credentials; explain the ownership/permission problem without deleting the file. `machinal place` shows non-secret locations; `getcredit` reads live credits without spending. Local mode uses its own device profile, never a hosted key.
24
+
25
+ On **Windows**, the following native credential rules apply:
26
+
23
27
  There is **one machinal application API key per Windows user**, not a separate OpenCode key or an AI-provider key:
24
28
 
25
29
  | Windows Credential Manager field | Value |
@@ -39,4 +43,4 @@ This is an OS credential, **not a project file**. The integration reads its secr
39
43
  - **`rate-limited` / HTTP 429:** retry later, without changing the key.
40
44
  - **`server-required`, `server-not-registered` or `server-configuration`:** inspect the existing approved registration. Do not send the saved key to a guessed, overridden or unrelated endpoint. Use the existing setup only when genuinely needed and preserve unrelated configuration.
41
45
 
42
- If `machinal_connection` itself is unavailable, inspect the client's MCP list/panel (`opencode mcp list` / `/mcps`, `claude mcp list`, or `codex mcp list`). The automatic vault/reconnect tool is specific to the installed Windows OpenCode integration; do not invent it for other clients. The installer/legacy launcher can read the saved credential on Windows without exposing it. Never reinstall, restart services or overwrite configuration just because Code Mode tools were initially hidden. Keep host approval controls enabled. Troubleshooting grants no media access or spending permission; after recovery, resume the original task within its existing consent scope.
46
+ If `machinal_connection` itself is unavailable, inspect the client's MCP list/panel (`opencode mcp list` / `/mcps`, `claude mcp list`, or `codex mcp list`). The automatic reconnect tool belongs to the installed OpenCode integration on Windows/Linux; do not invent it for other clients. Stdio adapters on both platforms read saved credentials without exposing them. Never reinstall, restart services or overwrite configuration just because Code Mode tools were initially hidden. Keep host approval controls enabled. Troubleshooting grants no media access or spending permission; after recovery, resume the original task within its existing consent scope.
package/src/bridge.mjs CHANGED
@@ -65,7 +65,7 @@ async function jsonResponse(response) {
65
65
  }
66
66
 
67
67
  export class MCPBridge {
68
- constructor({ url, localConfig, catalogFile, env = process.env, credentialStore = createCredentialStore(), fetchImpl = fetch, signal, notify = () => {} }) {
68
+ constructor({ url, localConfig, catalogFile, env = process.env, credentialStore = createCredentialStore({ env }), fetchImpl = fetch, signal, notify = () => {} }) {
69
69
  this.url = normalizeEndpoint(url);
70
70
  this.localConfig = localConfig;
71
71
  this.catalogFile = catalogFile;
@@ -82,6 +82,8 @@ export class MCPBridge {
82
82
 
83
83
  status() {
84
84
  return { ...this.state, transport: 'connected', mode: this.localConfig ? 'local' : 'server', endpoint: this.url,
85
+ credentialSource: this.credentialSource ?? 'unchecked',
86
+ ...(this.localConfig ? {} : { credentialStore: this.credentialStore?.description ?? { supported: false } }),
85
87
  service: this.localConfig ? 'Local' : this.url === MACHINAL_SERVER_URL ? 'Machinal Server' : 'Custom server',
86
88
  toolCount: this.tools.length, nextAction: this.localConfig && this.state.status !== 'connected'
87
89
  ? 'Check the saved independent local profile and Docker services. Rerun setup --mode local if its generated device token is invalid; a Machinal login is not needed.' : this.state.status === 'login_required'
@@ -101,12 +103,15 @@ export class MCPBridge {
101
103
  }
102
104
 
103
105
  async credentials() {
104
- if (this.localConfig) return localCredentials(this.localConfig, this.url);
106
+ if (this.localConfig) { this.credentialSource = 'local-profile'; return localCredentials(this.localConfig, this.url); }
105
107
  const environmentKey = this.env.MACHINAL_API_KEY || this.env.DIRECTION_API_KEY;
106
108
  if (environmentKey) {
109
+ this.credentialSource = 'environment';
107
110
  try { return validateAPIKey(environmentKey); } catch { throw Object.assign(new Error('Invalid credential'), { invalidKey: true }); }
108
111
  }
112
+ this.credentialSource = 'saved';
109
113
  const saved = await this.credentialStore?.read();
114
+ if (!saved) this.credentialSource = 'none';
110
115
  try { return saved ? validateAPIKey(saved) : null; } catch { throw Object.assign(new Error('Invalid credential'), { invalidKey: true }); }
111
116
  }
112
117
 
package/src/cli.mjs CHANGED
@@ -11,19 +11,23 @@ import { serveBridge, MCPBridge } from './bridge.mjs';
11
11
  import { VERSION } from './version.mjs';
12
12
  import { createLogger } from './presentation.mjs';
13
13
  import { createPromptUI } from './prompts.mjs';
14
+ import { manageLocal, managePlace, showCredits } from './commands.mjs';
15
+ import { readSettings } from './settings.mjs';
16
+ import { MACHINAL_SERVER_URL } from './endpoints.mjs';
14
17
 
15
- const HELP = `machinal MCP setup (Node.js 22.13+ or 24+)
18
+ const HELP = `Machinal · connect your agent
16
19
 
17
20
  npx @machinal/mcp setup
18
- npx @machinal/mcp setup --client opencode --mode server
19
- npx @machinal/mcp setup --client codex --mode custom --url https://YOUR-API/mcp
20
- npx @machinal/mcp setup --client claude --mode local --docker-dir PATH
21
- npx @machinal/mcp doctor --url https://YOUR-API/mcp
22
- npx @machinal/mcp launch opencode
23
- npx @machinal/mcp launch codex -- --help
24
- npx @machinal/mcp key set Save or replace the key (Windows)
25
- npx @machinal/mcp key set --url https://YOUR-API/mcp
26
- npx @machinal/mcp key delete Remove the saved key (Windows)
21
+ npx @machinal/mcp set-key Verify and save a key (hidden entry)
22
+ npx @machinal/mcp getcredit Show live credits; no spending
23
+ npx @machinal/mcp place Show processing, upload and download locations
24
+ npx @machinal/mcp place --downloads /absolute/folder --uploads /absolute/folder
25
+ npx @machinal/mcp local status
26
+ npx @machinal/mcp local install --docker-dir PATH
27
+
28
+ Global install: npm install -g @machinal/mcp · then use machinal <command>.
29
+ Also available: launch <client>, doctor --url URL, key set, key delete.
30
+ Requires Node.js 22.13+ (22.x) or 24+; Local needs Docker/Compose and a source checkout.
27
31
 
28
32
  Options for setup:
29
33
  --client opencode|claude|codex
@@ -57,9 +61,9 @@ Options for key set:
57
61
  --url URL Verify MCP access before replacing the saved key
58
62
 
59
63
  Machinal Server uses https://api.machinal.app/mcp automatically; no URL prompt.
60
- It reads MACHINAL_API_KEY, Windows Credential Manager, or hidden entry.
64
+ It reads MACHINAL_API_KEY, saved credentials, or hidden entry.
61
65
  Custom server asks for your own API URL; --url also selects custom mode for legacy scripts.
62
- Opt-in Windows saving uses Credential Manager, not plaintext client config.
66
+ Windows uses Credential Manager. Linux uses a private plaintext credentials.json (0600).
63
67
  Local mode asks for OPENROUTER_API_KEY and model settings, builds the source
64
68
  checkout with Docker, and keeps private provider settings outside the project.
65
69
  Local requires no Machinal account, subscription, credits or PocketBase.
@@ -89,9 +93,10 @@ function parseOptions(argv) {
89
93
  replace: { type: 'boolean' }, yes: { type: 'boolean' }, 'no-launch': { type: 'boolean' }, verbose: { type: 'boolean' },
90
94
  style: { type: 'string' }, 'no-skills': { type: 'boolean' }, 'replace-skills': { type: 'boolean' },
91
95
  'session-key': { type: 'boolean' },
92
- 'docker-dir': { type: 'string' }, 'start-docker': { type: 'boolean' },
96
+ 'docker-dir': { type: 'string' }, 'start-docker': { type: 'boolean' },
93
97
  transport: { type: 'string' }, 'defer-login': { type: 'boolean' }, 'configure-local': { type: 'boolean' },
94
98
  'local-config': { type: 'string' }, 'catalog-file': { type: 'string' },
99
+ downloads: { type: 'string' }, uploads: { type: 'string' },
95
100
  help: { type: 'boolean', short: 'h' }, version: { type: 'boolean', short: 'v' },
96
101
  },
97
102
  });
@@ -103,7 +108,10 @@ function parseOptions(argv) {
103
108
 
104
109
  export async function run(argv = process.argv.slice(2), runtime = {}) {
105
110
  const { values, positionals, forwarded } = parseOptions(argv);
106
- if (values.help) { console.log(HELP); return 0; }
111
+ if (values.help) {
112
+ console.log(values.verbose ? HELP : `${HELP.split('Options for setup:')[0]}Setup: --client opencode|claude|codex · --mode server|local|custom\nMore options: machinal --help --verbose\n`);
113
+ return 0;
114
+ }
107
115
  if (values.version) { console.log(VERSION); return 0; }
108
116
  const command = positionals[0] ?? 'setup';
109
117
  if (command === 'serve' || command === 'doctor') {
@@ -111,19 +119,41 @@ export async function run(argv = process.argv.slice(2), runtime = {}) {
111
119
  if (positionals.length !== 1 || forwarded.length || !values.url || Object.keys(values).some((key) => !allowed.includes(key))) throw new InstallerError('serve/doctor require --url and accept only --local-config and --catalog-file.');
112
120
  const options = { url: values.url, localConfig: values['local-config'], catalogFile: values['catalog-file'] };
113
121
  if (command === 'serve') return serveBridge(options, runtime);
114
- const bridge = new MCPBridge({ ...options, env: runtime.env ?? process.env, credentialStore: runtime.credentialStore ?? createCredentialStore() });
122
+ const bridge = new MCPBridge({ ...options, env: runtime.env ?? process.env, credentialStore: runtime.credentialStore === undefined ? createCredentialStore(runtime) : runtime.credentialStore });
115
123
  console.log(JSON.stringify(await bridge.connect(), null, 2));
116
124
  return bridge.state.status === 'connected' ? 0 : 1;
117
125
  }
118
126
  const context = {
119
127
  env: process.env, cwd: process.cwd(), launch: launchClient,
120
- credentialStore: createCredentialStore(),
121
128
  ...runtime,
122
129
  interactive: !values.yes && (runtime.interactive ?? (process.stdin.isTTY && process.stdout.isTTY)),
123
130
  };
131
+ if (context.credentialStore === undefined) context.credentialStore = createCredentialStore(context);
124
132
  context.ui ??= createPromptUI({ confirm, input, password, select }, { env: context.env });
125
- context.verbose = values.verbose || !context.interactive;
133
+ context.verbose = values.verbose === true;
126
134
  context.log ??= createLogger({ env: context.env });
135
+ const only = (allowed) => {
136
+ if (forwarded.length || Object.keys(values).some(key => !allowed.includes(key))) throw new InstallerError('Unsupported options for this command. Run machinal --help.');
137
+ };
138
+ if (['set-key', 'getcredit', 'credits', 'place'].includes(command)) {
139
+ if (positionals.length !== 1) throw new InstallerError('Do not pass API keys as arguments. Run machinal --help.');
140
+ if (command === 'set-key') {
141
+ only(['url']);
142
+ const settings = await readSettings(context);
143
+ if (!values.url && settings.connection?.mode === 'local') throw new InstallerError('Local mode uses a device token, not a Machinal key. Select a hosted endpoint explicitly with --url.');
144
+ return manageKey('set', { url: values.url ?? settings.connection?.url ?? MACHINAL_SERVER_URL }, context);
145
+ }
146
+ if (command === 'place') { only(['uploads', 'downloads']); return managePlace(values, context); }
147
+ only(['url', 'verbose']);
148
+ return showCredits(values, context);
149
+ }
150
+ if (command === 'local') {
151
+ const action = positionals[1] ?? 'status';
152
+ if (positionals.length > 2 || !['status', 'install'].includes(action)) throw new InstallerError('Use machinal local status or machinal local install.');
153
+ only(action === 'status' ? ['url'] : ['url', 'docker-dir', 'start-docker', 'configure-local', 'yes', 'verbose']);
154
+ return manageLocal(action, values, context);
155
+ }
156
+ if (values.uploads !== undefined || values.downloads !== undefined) throw new InstallerError('--uploads and --downloads belong to machinal place.');
127
157
  if (command === 'key' && positionals.length === 2 && ['set', 'delete'].includes(positionals[1]) && !forwarded.length) {
128
158
  const allowed = positionals[1] === 'set' ? ['url'] : ['yes'];
129
159
  if (Object.keys(values).some((option) => !allowed.includes(option))) {
@@ -135,6 +165,7 @@ export async function run(argv = process.argv.slice(2), runtime = {}) {
135
165
  if (values.transport && !['stdio', 'http'].includes(values.transport)) throw new InstallerError('Choose --transport stdio (default) or http (advanced).');
136
166
  if (values['local-config'] || values['catalog-file']) throw new InstallerError('Local profile/catalog paths are managed by setup, not provided as setup arguments.');
137
167
  if (values.transport === 'http') {
168
+ context.verbose = values.verbose || !context.interactive;
138
169
  if (values['defer-login'] || values['configure-local']) throw new InstallerError('--defer-login and --configure-local require the default stdio adapter.');
139
170
  if (values.mode === 'local') context.log('Advanced HTTP compatibility mode uses the existing authenticated self-hosted API. Omit --transport http for independent local mode.');
140
171
  return setup(values, context);
@@ -153,5 +184,5 @@ export async function run(argv = process.argv.slice(2), runtime = {}) {
153
184
  const { key } = credentials;
154
185
  return context.launch(client, key, { args: forwarded, cwd: context.cwd, env: context.env });
155
186
  }
156
- throw new InstallerError('Use setup, launch, key set, or key delete. Run --help for examples.');
187
+ throw new InstallerError('Use setup, set-key, getcredit, place, local, launch, or key delete. Run --help.');
157
188
  }
@@ -0,0 +1,89 @@
1
+ import { lstat, realpath } from 'node:fs/promises';
2
+ import { isAbsolute } from 'node:path';
3
+ import { checkConnection, normalizeEndpoint } from './connection.mjs';
4
+ import { localCredentials } from './bridge.mjs';
5
+ import { compactCreditSummaryLines, creditSummaryLines } from './credits.mjs';
6
+ import { MACHINAL_SERVER_URL, DEFAULT_LOCAL_URL } from './endpoints.mjs';
7
+ import { InstallerError } from './errors.mjs';
8
+ import { readKey } from './keys.mjs';
9
+ import { prepareIndependentLocal } from './local-setup.mjs';
10
+ import { endpointFiles } from './runtime.mjs';
11
+ import { readSettings, saveSettings, settingsFile } from './settings.mjs';
12
+
13
+ export async function showCredits(values, context) {
14
+ const settings = await readSettings(context);
15
+ const endpoint = normalizeEndpoint(values.url ?? settings.connection?.url ?? MACHINAL_SERVER_URL);
16
+ const local = !values.url && settings.connection?.mode === 'local';
17
+ const key = local ? await localCredentials(settings.connection.localConfig, endpoint)
18
+ : (await readKey({ ...context, interactive: false })).key;
19
+ const result = await (context.checkConnection ?? checkConnection)(endpoint, key, { local });
20
+ if (local && !result.local) throw new InstallerError('The saved endpoint is not the independent local backend. No hosted key was sent.');
21
+ if (result.local) {
22
+ context.log('Local mode: no Machinal credits. AI is billed by your provider.');
23
+ return 0;
24
+ }
25
+ if (!result.credits) throw new InstallerError(result.creditsWarning ?? 'Live credits unavailable. No balance was assumed.');
26
+ for (const line of (context.verbose ? creditSummaryLines : compactCreditSummaryLines)(result.credits)) context.log(line);
27
+ return 0;
28
+ }
29
+
30
+ async function existingDirectory(value) {
31
+ if (!isAbsolute(value)) throw new InstallerError('Use an absolute folder path. No directory was created or scanned.');
32
+ try {
33
+ const path = await realpath(value);
34
+ if (!(await lstat(path)).isDirectory()) throw new Error();
35
+ return path;
36
+ } catch { throw new InstallerError('The selected folder does not exist or is not accessible. No files were read or transferred.'); }
37
+ }
38
+
39
+ export async function managePlace(values, context) {
40
+ const patch = {};
41
+ if (values.downloads !== undefined) patch.downloadDirectory = await existingDirectory(values.downloads);
42
+ if (values.uploads !== undefined) patch.uploadDirectory = await existingDirectory(values.uploads);
43
+ const settings = Object.keys(patch).length ? await saveSettings(patch, context) : await readSettings(context);
44
+ const { connection } = settings;
45
+ context.log('Machinal locations', 'heading');
46
+ context.log(`CLI backend: ${connection ? `${connection.mode} · ${connection.url}` : 'not configured; run machinal setup'}`);
47
+ context.log(`Uploads: named project volume${settings.uploadDirectory ? ` · source folder ${settings.uploadDirectory}` : ' · choose exact source files'}`);
48
+ context.log(`Downloads: ${settings.downloadDirectory ?? 'ask each time (or use the server-saved preference)'}`);
49
+ context.log(`Settings: ${settingsFile(context)}`);
50
+ if (context.credentialStore?.description?.path) context.log(`Key: ${context.credentialStore.description.path} (plaintext, owner-only)`);
51
+ if (connection?.localConfig) context.log(`Local profile: ${connection.localConfig}`);
52
+ if (Object.keys(patch).length) context.log('Folders saved. No files uploaded or downloaded.');
53
+ return 0;
54
+ }
55
+
56
+ export async function manageLocal(action, values, context) {
57
+ const settings = await readSettings(context);
58
+ const endpoint = normalizeEndpoint(values.url ?? (settings.connection?.mode === 'local' ? settings.connection.url : DEFAULT_LOCAL_URL));
59
+ const { localConfig } = endpointFiles(endpoint, context);
60
+ if (action === 'status') {
61
+ let installed;
62
+ try { installed = await lstat(localConfig); } catch (error) { if (error.code !== 'ENOENT') throw new InstallerError('The local profile is not accessible.'); }
63
+ if (!installed) { context.log('Local backend: not installed. Run machinal local install --docker-dir PATH.'); return 1; }
64
+ let key;
65
+ try { key = await localCredentials(localConfig, endpoint); } catch {
66
+ context.log('Local backend: profile invalid or unreadable. Check its ownership, permissions and device token; no file was changed.');
67
+ return 1;
68
+ }
69
+ try {
70
+ const result = await (context.checkConnection ?? checkConnection)(endpoint, key, { local: true });
71
+ if (!result.local) throw new InstallerError('The endpoint is not an independent local backend.');
72
+ context.log(`Local backend: ready · ${endpoint}`);
73
+ return 0;
74
+ } catch { context.log('Local backend: configured, not verified. Run machinal local install to start it; check Docker and the local device token.'); return 1; }
75
+ }
76
+ const profile = await prepareIndependentLocal(values, endpoint, localConfig, context);
77
+ let result;
78
+ const verify = () => (context.checkConnection ?? checkConnection)(endpoint, profile.key, { local: true });
79
+ try { result = await verify(); } catch (error) {
80
+ if (error.code !== 'network') throw error;
81
+ await profile.start();
82
+ result = await verify();
83
+ }
84
+ if (!result.local) throw new InstallerError('The endpoint is not the independent local backend. Connection settings were not changed.');
85
+ await saveSettings({ connection: { mode: 'local', url: endpoint, localConfig } }, context);
86
+ context.log(`Local backend: ready · ${endpoint}`);
87
+ context.log('Next: machinal setup --mode local to connect your agent.');
88
+ return 0;
89
+ }
@@ -3,8 +3,11 @@ import { lstat, mkdir, open, readFile, rename, unlink } from 'node:fs/promises';
3
3
  import { homedir } from 'node:os';
4
4
  import { dirname, join } from 'node:path';
5
5
  import { InstallerError } from './errors.mjs';
6
- import { bridgeEntry, serverEntry, updateJSON, updateTOML } from './formats.mjs';
7
- import { configureOpenCodeAuth, removeOpenCodeAuthServer } from './opencode-configuration.mjs';
6
+ import { bridgeEntry, parseJSONConfiguration, serverEntry, updateJSON, updateTOML } from './formats.mjs';
7
+ import { configureOpenCodeAuth, removeOpenCodeAuthServer, upgradeOpenCodeAuth } from './opencode-configuration.mjs';
8
+ import { isManagedRuntimeCommand } from './runtime.mjs';
9
+ import { isDeepStrictEqual } from 'node:util';
10
+ import { parse } from 'jsonc-parser';
8
11
 
9
12
  const MAX_CONFIG_BYTES = 2 * 1024 * 1024;
10
13
 
@@ -18,7 +21,7 @@ async function exists(file) {
18
21
  }
19
22
  }
20
23
 
21
- async function chooseJSONFile(directory) {
24
+ export async function chooseJSONFile(directory) {
22
25
  const json = join(directory, 'opencode.json');
23
26
  const jsonc = join(directory, 'opencode.jsonc');
24
27
  const [hasJSON, hasJSONC] = await Promise.all([exists(json), exists(jsonc)]);
@@ -72,9 +75,16 @@ export async function planConfiguration(options) {
72
75
  const updated = options.client === 'codex'
73
76
  ? updateTOML(previous.original ?? '', options.name, entry)
74
77
  : updateJSON(previous.original ?? '', options.client, options.name, entry);
75
- const automaticAuth = options.client === 'opencode' && !options.localConfig && (options.platform ?? process.platform) === 'win32';
76
- if (automaticAuth) updated.content = configureOpenCodeAuth(updated.content, options.name, options.url, options.transport === 'stdio' ? entry.command : undefined);
78
+ const automaticAuth = options.client === 'opencode' && !options.localConfig && ['win32', 'linux'].includes(options.platform ?? process.platform);
79
+ if (options.client === 'opencode' && options.transport === 'stdio') {
80
+ const current = parse(previous.original ?? '{}').mcp?.servers?.[options.name];
81
+ if (current && isManagedRuntimeCommand(current.command, options)
82
+ && isDeepStrictEqual({ ...current, command: [current.command[0], options.script, ...current.command.slice(2)] }, entry)) updated.conflict = false;
83
+ }
84
+ if (automaticAuth) updated.content = configureOpenCodeAuth(updated.content, options.name, options.url, options.transport === 'stdio' ? entry.command : undefined, options);
85
+ if (automaticAuth && options.transport === 'stdio') updated.content = upgradeOpenCodeAuth(updated.content, options);
77
86
  if (options.client === 'opencode' && options.localConfig) updated.content = removeOpenCodeAuthServer(updated.content, options.name);
87
+ if (options.client === 'opencode') parseJSONConfiguration(updated.content, 'opencode');
78
88
  return { file, ...previous, ...updated, automaticAuth };
79
89
  }
80
90
 
@@ -1,4 +1,7 @@
1
1
  import { InstallerError } from './errors.mjs';
2
+ import { join } from 'node:path';
3
+ import { stateDirectory } from './paths.mjs';
4
+ import { deletePrivateJSON, readPrivateJSON, writePrivateJSON } from './private-json.mjs';
2
5
 
3
6
  export const WINDOWS_CREDENTIAL = Object.freeze({
4
7
  service: 'Machinal/mcp',
@@ -16,7 +19,25 @@ export function createCredentialStore({
16
19
  load = () => import('@napi-rs/keyring'),
17
20
  service = WINDOWS_CREDENTIAL.service,
18
21
  account = WINDOWS_CREDENTIAL.account,
22
+ home,
23
+ env = process.env,
19
24
  } = {}) {
25
+ if (platform === 'linux') {
26
+ const path = join(stateDirectory({ home, env, platform }), 'credentials.json');
27
+ return {
28
+ description: { name: 'Private credentials file', backend: 'file', path, plaintext: true },
29
+ async read() {
30
+ const value = await readPrivateJSON(path);
31
+ if (value === null) return null;
32
+ if (value.version !== 1 || typeof value.apiKey !== 'string') {
33
+ throw new InstallerError('The saved credentials file is invalid. Run machinal set-key to replace it; no key was deleted.');
34
+ }
35
+ return value.apiKey;
36
+ },
37
+ async write(key) { await writePrivateJSON(path, { version: 1, apiKey: key }); },
38
+ async delete() { return deletePrivateJSON(path); },
39
+ };
40
+ }
20
41
  if (platform !== 'win32') return null;
21
42
 
22
43
  let modulePromise;
@@ -30,6 +51,7 @@ export function createCredentialStore({
30
51
  ));
31
52
 
32
53
  return {
54
+ description: { name: 'Windows Credential Manager', ...WINDOWS_CREDENTIAL },
33
55
  async read() {
34
56
  try {
35
57
  const current = await (await getEntry()).getPassword();