@1endpoint/coding-helper 0.1.1 → 0.1.2

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 (2) hide show
  1. package/README.md +128 -75
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,123 +1,176 @@
1
1
  # @1endpoint/coding-helper
2
2
 
3
- Safe, isolated setup for **DeepSeek Harness** and **Claude Code CLI** using the single 1endpoint API base URL:
3
+ Connect **DeepSeek Harness** or **Claude Code** to 1endpoint with an interactive setup menu. Choose your language, select models, and manage your connection without editing configuration files by hand.
4
4
 
5
- ```text
6
- https://1endpoint.dev/api/v1
5
+ ## Before you start
6
+
7
+ - Install **Node.js 22.19 or newer**.
8
+ - Install [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) or [Claude Code](https://code.claude.com/docs/en/overview) separately. The helper configures these tools; it does not install them.
9
+ - Have a 1endpoint API key ready. Keep it private: do not paste it into command arguments, shared configuration files or a repository.
10
+
11
+ ## 1. Open the helper
12
+
13
+ Run this in your terminal:
14
+
15
+ ```bash
16
+ npx @1endpoint/coding-helper
7
17
  ```
8
18
 
9
- **Release status: not yet published to npm.** The following registry commands become available only after the maintainer publishes the package. Until then, run the local executable or a reviewed tarball. This helper is an independent integration, not an official DeepSeek or Anthropic product.
19
+ 1. Choose **English** or **Tiếng Việt**.
20
+ 2. Choose **Setup**.
21
+ 3. Select **DSH** or **Claude Code**.
22
+ 4. Select models from the 1endpoint catalog.
23
+ 5. Review the selection, then choose **Confirm**.
24
+
25
+ Use **↑ / ↓** to move and **Enter** to select. Press **Escape** to cancel. Confirmation is a selection, not a typed `y/n` answer.
26
+
27
+ ### Choosing models
28
+
29
+ For DSH, choose the model you want to use by default.
30
+
31
+ For Claude Code, choose a 1endpoint model for each tier: **Haiku**, **Sonnet** and **Opus**. Each tier can use a different model. Sonnet is used as the main/default selection. Select optional **Fable** mapping only if your installed Claude Code version supports that tier; otherwise keep the standard three-tier option.
10
32
 
11
- ## Requirements
33
+ If the catalog cannot be loaded, choose **Retry**, explicitly choose **Manual model ID**, or **Cancel**. The helper does not silently substitute a model.
12
34
 
13
- - Node.js **22.19 or newer** (tested locally on Node 24).
14
- - Install the desired coding tool separately from its official distribution. The helper does not download tools or run installation scripts.
15
- - An enabled public model ID from the [1endpoint model catalog](https://console.1endpoint.dev/models).
16
- - Set `ONEENDPOINT_API_KEY` in the launching process environment using your shell or secret manager. Never put the key in command arguments, a Git repository, or a shared configuration file.
35
+ ## 2. Provide your API key
17
36
 
18
- ## Setup
37
+ The helper does **not** save your API key. Set `ONEENDPOINT_API_KEY` in the terminal where you will launch the tool, using your secret manager or a hidden prompt.
19
38
 
20
- After publication:
39
+ For **Bash**, the following prompt keeps the key out of the command itself and hides it while you type:
21
40
 
22
41
  ```bash
23
- npx @1endpoint/coding-helper
24
- # First choose English / Tiếng Việt, then the action.
25
- # Colorful menu: use ↑/↓ and Enter; Escape cancels. No typed y/n.
26
- # Setup, reconfigure, remove, diagnose and run are available in the menu.
27
- # Fetches public 1endpoint text models for selection; Claude tiers map independently.
28
- # Or explicit, scriptable setup:
29
- npx @1endpoint/coding-helper setup --tool dsh --model your-model-id --dry-run
30
- npx @1endpoint/coding-helper setup --tool dsh --model your-model-id
31
- npx @1endpoint/coding-helper setup --tool claude --model your-model-id
42
+ read -r -s -p "1endpoint API key: " ONEENDPOINT_API_KEY
43
+ printf '\n'
44
+ export ONEENDPOINT_API_KEY
45
+ ```
46
+
47
+ For another shell, use its secure environment-variable mechanism or your secret manager. Do not type a real key into a command you intend to share. A key set in one terminal is not automatically available in another terminal or after restarting the shell.
48
+
49
+ ## 3. Check the connection setup
50
+
51
+ For DSH:
52
+
53
+ ```bash
54
+ npx @1endpoint/coding-helper doctor --tool dsh
32
55
  ```
33
56
 
34
- Before publication, from the repository:
57
+ For Claude Code:
35
58
 
36
59
  ```bash
37
- yarn install --immutable
38
- yarn test
39
- node src/cli.mjs setup --tool dsh --model your-model-id --dry-run
40
- node src/cli.mjs setup --tool dsh --model your-model-id
60
+ npx @1endpoint/coding-helper doctor --tool claude
41
61
  ```
42
62
 
43
- **After setup or reconfigure, restart the DSH/Claude Code session for changes to take effect. An already-open session does not update automatically. Start the new session through `coding-helper run`, not the original tool command, to use the isolated helper profile.**
63
+ Doctor checks your saved connection configuration, whether the tool is installed, and whether the key environment variable is present. It does not validate the key against the server or make an inference request.
64
+
65
+ ## 4. Start a new tool session
44
66
 
45
- The wizard begins with **English / Tiếng Việt** selection before configuration/reconfiguration/deletion. It fetches the public 1endpoint text model catalog for arrow-key choices. Claude's Haiku, Sonnet and Opus tiers can each map to a different public model; optional Fable mapping is available for versions supporting that tier. The helper does not infer vendor/model equivalence from names. If catalog loading fails, choose Retry, explicit manual ID entry, or Cancel.
67
+ **After setup or reconfiguration, close the old tool session and start a new session through the helper. An already-open session does not pick up the new connection or model mapping.**
46
68
 
47
- Setup never asks for, reads, validates or stores your API key. It creates only helper-owned files under `~/.1endpoint/coding-helper`. Use an absolute `ONEENDPOINT_HELPER_HOME` to choose a different state directory. Dry-run makes no writes. Existing DSH and Claude user configuration is not edited or imported.
69
+ Start DSH:
48
70
 
49
- ## Diagnose and launch
71
+ ```bash
72
+ npx @1endpoint/coding-helper run --tool dsh
73
+ ```
50
74
 
51
- After setting the key in your process environment:
75
+ Start Claude Code:
52
76
 
53
77
  ```bash
54
- coding-helper doctor --tool dsh
55
- coding-helper run --tool dsh
56
- coding-helper run --tool dsh --profile headless -- 'Reply exactly OK'
57
- coding-helper doctor --tool claude
58
- coding-helper run --tool claude
59
- coding-helper run --tool claude -- -p 'Reply exactly OK'
78
+ npx @1endpoint/coding-helper run --tool claude
60
79
  ```
61
80
 
62
- For npx-only use, replace `coding-helper` with `npx @1endpoint/coding-helper`. For local use, replace it with `node src/cli.mjs`.
81
+ You can also reopen the helper and select **Run**.
63
82
 
64
- `doctor` verifies owned-file integrity, CLI availability and whether the key environment variable is present. It does **not** validate credentials, make network requests, call inference, execute an apiKeyHelper or read your original tool credentials. `run` is explicit consent to launch the selected tool; tool startup and inference can contact networks and incur charges. Permission/trust prompts remain tool-owned. Authentication, provider health and real inference are separate from local configuration tests.
83
+ **Use the helper to launch the configured session.** Running `dsh` or `claude` directly uses the tool's ordinary configuration, not this helper connection. Tool requests may incur charges; the tool's normal permission and workspace-trust prompts remain active.
65
84
 
66
- ### DeepSeek Harness
85
+ ### Important Claude Code behavior
67
86
 
68
- - Uses a separate `DSH_HOME` plus a dedicated `--patch` overlay.
69
- - Configures the native `llm-pi-ai` provider with `api: openai-completions`, `baseURL` and `apiKeyEnv: ONEENDPOINT_API_KEY`.
70
- - Configures the native `agent-default-model` selection. No secret interpolation, custom proxy or injected agent instruction is required.
71
- - Supported profiles: `web`, `headless`, `acp`, `sdk`. `sdk-minimal` lacks the required entries and is deliberately rejected.
72
- - The helper does not reuse current sessions, plugins, model presets or provider configurations. Existing sessions can retain their own model selection; start a new session in the isolated profile.
73
- - DSH owns request assembly, conversation state, streaming, tool loops and permissions. The helper only sets the connection.
74
- - Verified configuration contract: DSH `0.2.1-alpha.3`. This prerelease contract may change. A successful dump exit code alone is insufficient: the integration tests also inspect provider and selected-model rows. The shipped Web schema dump has a separate preset/tree-carrier failure; headless schema validation is the supported check.
87
+ The helper uses an isolated configuration. **Project/local settings, including their hooks and permissions, are not loaded in this mode.** Managed organization policy still applies, and the helper does not enable permission bypass. If your project requires those local restrictions or hooks, use your organization's approved configuration instead.
75
88
 
76
- ### Claude Code CLI
89
+ ### Important DSH behavior
77
90
 
78
- - Uses a separate `CLAUDE_CONFIG_DIR`, a helper-owned `--settings` file and `--setting-sources user`.
79
- - **Project and local settings, including their hooks and permissions, are intentionally not loaded.** This is a tradeoff for deterministic routing, not transparent preservation of project behavior. Managed/organization policy still applies and can override the connection. Do not use this mode if those project restrictions are required; configure the tool manually with your administrator instead.
80
- - The raw process key becomes `ANTHROPIC_AUTH_TOKEN` in the child environment only. The CLI constructs the Bearer header. No key is written to settings or included in argv.
81
- - Maps main, Opus, Sonnet, Haiku, optional Fable and default subagent roles. The wizard offers distinct catalog selections per tier; scripted setup accepts `--haiku-model`, `--sonnet-model`, `--opus-model` and optional `--fable-model`. `--model` is the main/default fallback; explicit role selections take priority. Without a Fable mapping it follows the Opus selection. Explicit model IDs in agent/skill definitions or managed policy are outside that default mapping; no promise is made to rewrite every model choice.
82
- - Clears inherited conflicting Anthropic/cloud authentication and routing variables in the child only. It does not log out, modify the parent's environment, bypass permission prompts or execute existing key helpers.
83
- - Uses the same universal base URL above. Claude appends `/v1/messages`, producing `/api/v1/v1/messages`, a supported gateway alias. Do not change the base to a different per-client URL.
84
- - Claude owns request assembly, conversation state, streaming and tool execution. Version verification and fixture boundaries are recorded in the release checklist.
91
+ DSH runs with a separate home, so your ordinary sessions, plugins and provider settings are not imported or changed. Supported profiles are `web` (default), `headless`, `acp` and `sdk`; `sdk-minimal` is not supported.
85
92
 
86
- ## Update, backup and recovery
93
+ ## Change models
94
+
95
+ Open the helper again, select **Reconfigure**, choose the tool, and select new models:
96
+
97
+ ```bash
98
+ npx @1endpoint/coding-helper
99
+ ```
100
+
101
+ The previous connection configuration is backed up automatically. **Restart the tool session through the helper after confirming the change.**
102
+
103
+ For scripted use, preview and apply a DSH model change:
87
104
 
88
105
  ```bash
89
- coding-helper backup --tool dsh
90
- coding-helper reconfigure --tool dsh --model another-public-model --dry-run
91
- coding-helper reconfigure --tool dsh --model another-public-model
92
- coding-helper remove --tool dsh --dry-run
93
- coding-helper remove --tool dsh --yes
106
+ npx @1endpoint/coding-helper reconfigure --tool dsh --model your-model-id --dry-run
107
+ npx @1endpoint/coding-helper reconfigure --tool dsh --model your-model-id
94
108
  ```
95
109
 
96
- `reconfigure` validates the unchanged helper manifest/configuration, automatically backs up the verified old connection configuration and changes the model. Legacy `setup --update` is also available. Backups contain only generated configuration, never keys. Identical setup is idempotent. Normal setup refuses unknown files, modified configuration, malformed manifests and symlink state paths. Writes use an exclusive setup lock, private file permissions and atomic replacement; failed configuration writes attempt rollback.
110
+ Replace `your-model-id` with the exact public model ID you want to use. Replace `dsh` with `claude` for Claude Code. To set separate Claude tiers explicitly:
111
+
112
+ ```bash
113
+ npx @1endpoint/coding-helper reconfigure --tool claude \
114
+ --model your-main-model-id \
115
+ --haiku-model your-fast-model-id \
116
+ --sonnet-model your-balanced-model-id \
117
+ --opus-model your-strong-model-id
118
+ ```
97
119
 
98
- `remove` previews with `--dry-run` and requires explicit `--yes` to delete the selected tool's generated connection file and manifest. It preserves runtime homes, conversations, backups, unrelated files and all original tool settings. **Stop the corresponding tool before removing its connection configuration.** To return to normal tools, launch `dsh` or `claude` directly without the helper.
120
+ An optional `--fable-model` sets Fable explicitly. Without it, Fable follows Opus. Explicit tier selections take priority over the `--model` fallback. Explicit model IDs in your own agent/skill definitions or managed policy are not rewritten by these default mappings.
99
121
 
100
- For corrupted or hand-modified helper configuration, use `coding-helper remove --tool dsh --force --yes` (or `claude`), then run setup again. Force recovery targets only the fixed helper-generated connection file and manifest, never paths read from a damaged manifest; it does not copy potentially secret-bearing tampered content into backups. Symlinks remain refused even in force mode. There is no need to find and delete configuration files manually. Runtime homes may contain tool-created conversations or credentials; they are intentionally retained, not silently wiped or backed up. Do not share or commit them. A stale setup lock still requires reviewing that no setup is active before retrying; do not defeat a live writer lock.
122
+ ## Remove the connection
101
123
 
102
- This is configuration isolation, **not an OS sandbox**. The coding tools still have their ordinary filesystem/network access and can create runtime data. No unattended install, background daemon, automatic paid smoke, telemetry or global config migration is included.
124
+ Stop the tool session first. Open the helper, select **Remove**, choose the tool and confirm the removal. You do not need to find or delete configuration files yourself.
103
125
 
104
- ## Development and packaging
126
+ Alternatively, preview and confirm removal:
105
127
 
106
128
  ```bash
107
- yarn install --immutable
108
- yarn check
109
- yarn test
110
- yarn pack --out ../coding-helper-0.1.0.tgz
129
+ npx @1endpoint/coding-helper remove --tool dsh --dry-run
130
+ npx @1endpoint/coding-helper remove --tool dsh --yes
111
131
  ```
112
132
 
113
- No production dependencies and no build step. The published entry is native ESM. Package contents are allowlisted. See the [publishing guide](docs/PUBLISHING.md) for step-by-step npm authentication, first publication, verification, updates and troubleshooting. See the [release checklist](docs/RELEASE.md) for current verification boundaries. Publishing is a separate maintainer action; creating or pushing the repository does not publish npm.
133
+ Use `--tool claude` for Claude Code. Removal deletes only the helper-generated connection configuration. **Your original tool settings, runtime conversations and configuration backups are preserved.** To return to your ordinary setup, launch `dsh` or `claude` directly.
134
+
135
+ ### Recover from damaged connection configuration
136
+
137
+ If the helper reports that its generated configuration has been modified or corrupted, choose **Force removal recovery** in the Remove menu, review the warning and confirm. Then run Setup again.
138
+
139
+ For scripted recovery:
140
+
141
+ ```bash
142
+ npx @1endpoint/coding-helper remove --tool dsh --force --yes
143
+ ```
144
+
145
+ Force removal deletes only the fixed helper connection files, including modified contents, without backing up those modified contents. It still preserves original tool settings and runtime conversations. Use it only for recovery, not routine reconfiguration.
146
+
147
+ ## Configuration and privacy
148
+
149
+ - The shared API base URL is `https://1endpoint.dev/api/v1`.
150
+ - Connection configuration is stored under `~/.1endpoint/coding-helper`. Set an absolute `ONEENDPOINT_HELPER_HOME` if you need a different location.
151
+ - Setup does not overwrite your existing DSH or Claude Code configuration.
152
+ - The interactive menu fetches the public text-model catalog without sending your API key. Explicit setup, reconfigure and doctor commands work locally.
153
+ - Your key is supplied to the launched tool through its process environment, not saved in the helper's connection files.
154
+ - Runtime tools can create their own session data. Keep their isolated homes private.
155
+ - Configuration isolation is **not an operating-system sandbox**; the tools retain their ordinary filesystem and network access.
114
156
 
115
- ## Reference and attribution
157
+ This is an independent integration, not an official DeepSeek or Anthropic product.
116
158
 
117
- The onboarding/product design was reviewed against [Z.AI coding-helper](https://www.npmjs.com/package/@z_ai/coding-helper) `0.1.1`: wizard, per-tool setup and doctor. Its registry metadata labels the package Proprietary. No implementation code is copied; this is an independent implementation with an explicit test suite, no stored API keys, and no automatic tool installation. The reference has no DSH support and is not authority for the DSH configuration contract.
159
+ ## Troubleshooting
118
160
 
119
- Official references: [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness), [Claude gateway setup](https://code.claude.com/docs/en/llm-gateway-connect), [settings](https://code.claude.com/docs/en/settings), [models](https://code.claude.com/docs/en/model-config).
161
+ | Problem | What to do |
162
+ | --- | --- |
163
+ | Node version error | Install Node.js 22.19 or newer, then reopen your terminal. |
164
+ | CLI not found | Install the selected coding tool and make sure its executable is on your `PATH`. |
165
+ | API key missing | Set `ONEENDPOINT_API_KEY` in the same terminal, then run Doctor again. |
166
+ | Catalog unavailable | Choose Retry, or explicitly choose manual entry with a known public model ID. |
167
+ | New model is not taking effect | Close the old session and start a new one with the helper's Run action. |
168
+ | Ordinary tool launch ignores the helper | Launch through `npx @1endpoint/coding-helper run --tool dsh` or `--tool claude`. |
169
+ | Generated configuration is damaged | Use Remove → Force removal recovery, then Setup again. |
170
+ | Authentication or model request fails | Confirm your key, model access and account balance in 1endpoint. Doctor does not validate server-side access. |
120
171
 
121
- ## Tiếng Việt
172
+ ## More help
122
173
 
123
- Helper hỗ trợ ưu tiên DeepSeek Harness và Claude Code CLI; dùng một base URL chung, home riêng và API key từ biến môi trường. Không sửa cấu hình công cụ đang dùng, không lưu key, không tự cài công cụ và không tự gọi inference có phí. `setup --dry-run` xem trước; `doctor` chỉ kiểm tra cục bộ; `run` mới khởi chạy công cụ. Claude chạy ở chế độ này **không nạp settings/hook/quyền project-local**; chính sách quản trị vẫn có hiệu lực. Package chưa publish: dùng lệnh local ở trên cho tới khi maintainer phát hành. Hướng dẫn Console có cả EN/VI.
174
+ - [Console usage guide](https://console.1endpoint.dev/docs/guides/coding-tools/coding-helper)
175
+ - [Report a problem](https://github.com/dothinh115/1endpoint-coding-helper/issues)
176
+ - Maintainers: [publishing](docs/PUBLISHING.md) and [release verification](docs/RELEASE.md).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@1endpoint/coding-helper",
3
- "version": "0.1.1",
3
+ "version": "0.1.2",
4
4
  "description": "Safe isolated 1endpoint setup for DeepSeek Harness and Claude Code CLI",
5
5
  "type": "module",
6
6
  "bin": {