@este.systems/dsc 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Este Systems
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,408 @@
+# dsc
+
+A CLI coding agent for [DeepSeek](https://api-docs.deepseek.com/).
+Streams responses, calls tools (`bash`, `read_file`, `write_file`, `edit_file`,
+`grep`, `glob`, `web_fetch`, `web_search`), keeps per-cwd sessions, and runs
+in your terminal as a plain readline REPL — output stays selectable / pasteable
+and approvals happen inline.
+
+## Install
+
+dsc requires **Node 22+** (it uses `fs.promises.glob`, stable since 22.0).
+
+### Step 1 — install Node 22+
+
+| Platform | One-liner |
+|---|---|
+| **Linux (Debian/Ubuntu)** | `curl -fsSL https://deb.nodesource.com/setup_22.x \| sudo -E bash - && sudo apt install -y nodejs` |
+| **Linux (Fedora/RHEL)** | `sudo dnf install -y nodejs:22/common` |
+| **Linux (Arch)** | `sudo pacman -S nodejs npm` |
+| **macOS** | `brew install node@22 && brew link node@22` |
+| **Windows (winget)** | `winget install OpenJS.NodeJS.LTS` |
+| **Windows (scoop)** | `scoop install nodejs-lts` |
+| **Cross-platform (nvm)** | `nvm install 22 && nvm use 22` |
+
+Verify: `node --version` should print `v22.x.x` or higher.
+
+### Step 2 — install dsc
+
+Three options. Once the package is published to npm, **(A)** is what you want.
+Today, use **(B)** for a frozen tarball or **(C)** if you'll be hacking on the
+source.
+
+**(A) From npm** *(after publish)*:
+
+```sh
+npm install -g @este.systems/dsc
+```
+
+**(B) From a local tarball** *(works on all platforms with the same npm)*:
+
+```sh
+git clone https://github.com/EsteSystems/dsc.git
+cd dsc
+npm install
+npm run package      # produces pkg/<name>-<version>.tgz
+```
+
+then on **Linux / macOS**:
+
+```sh
+scripts/install.sh
+```
+
+or on **Windows PowerShell**:
+
+```powershell
+.\scripts\install.ps1
+```
+
+Both wrappers just call `npm install -g pkg/*.tgz` after auto-finding the
+tarball.
+
+**(C) From source for development** *(live edits, no rebuild step)*:
+
+```sh
+git clone https://github.com/EsteSystems/dsc.git
+cd dsc
+npm install
+npm link             # exposes `dsc` globally
+```
+
+The shim in `bin/dsc.mjs` runs the TypeScript sources directly through
+`tsx`, so your next `dsc` launch picks up edits immediately. If `tsx`
+isn't available it falls back to `dist/` (populate with `npm run build`).
+
+### Step 3 — verify
+
+```sh
+dsc --help
+```
+
+If you get "command not found", your shell's `PATH` doesn't include npm's
+global-bin directory. Find it with `npm config get prefix`; the binary
+lives in `<prefix>/bin` on Linux/macOS or `<prefix>` on Windows. Add that
+to your `PATH` and reopen the terminal.
+
+## API key
+
+dsc reads its DeepSeek key from `~/.config/deepseek/deepseek.json` on every
+platform — Node's `os.homedir()` resolves to `C:\Users\<you>` on Windows, so
+the actual file path is `C:\Users\<you>\.config\deepseek\deepseek.json`. Set
+`XDG_CONFIG_HOME` if you'd rather put it elsewhere.
+
+**Linux / macOS:**
+
+```sh
+mkdir -p ~/.config/deepseek
+cat > ~/.config/deepseek/deepseek.json <<'JSON'
+{
+  "api_key": "sk-..."
+}
+JSON
+chmod 600 ~/.config/deepseek/deepseek.json
+```
+
+**Windows PowerShell:**
+
+```powershell
+$dir = "$HOME\.config\deepseek"
+New-Item -ItemType Directory -Force -Path $dir | Out-Null
+'{"api_key":"sk-..."}' | Set-Content -Path "$dir\deepseek.json" -Encoding utf8
+```
+
+Accepted shapes:
+
+```jsonc
+{ "api_key": "sk-..." }                                   // simple
+{ "DEEPSEEK_API_KEY": "sk-..." }                          // alt key
+{ "env": { "DEEPSEEK_API_KEY": "sk-..." } }               // env-style
+{ "env": { "ANTHROPIC_AUTH_TOKEN": "sk-..." } }           // claude-switcher compat
+```
+
+The env var `DEEPSEEK_API_KEY` takes priority over the file when set.
+
+## Quick start
+
+```sh
+dsc                                  # interactive REPL
+dsc "summarize src/api.ts"           # one-shot
+dsc --yolo "rename Foo to Bar"       # skip approval prompts
+dsc -m deepseek-v4-flash             # pick a model
+dsc --no-resume                      # fresh session, ignore prior history
+dsc --resume <id>                    # resume a specific session id
+```
+
+## REPL commands
+
+| Command | What it does |
+|---|---|
+| `/clear` | Start a new session. Old session stays on disk. |
+| `/cost` | Show token usage and estimated cost so far. |
+| `/model [name]` | Show or switch model. Available: `deepseek-v4-pro`, `deepseek-v4-flash`. |
+| `/yolo` | Toggle approval mode (write/edit/bash/web_fetch). |
+| `/reasoning [on\|off]` | Show/hide `reasoning_content` from thinking models. Default on. |
+| `/list` | List sessions in the current cwd. The active session is marked with `*`. |
+| `/resume <#\|id\|last>` | Resume a session by index (from `/list`), id, or `last`. |
+| `/audit` | Print the path of the JSONL audit log. |
+| `/transcript` | Print the full conversation, including any messages compaction archived. |
+| `/compact [N]` | Summarize older turns into a synthetic block (kept in the system prompt) and move them to the archive. Keeps the last `N` user turns verbatim (default 4). Cumulative across re-runs. |
+| `/edit [text]` | Open `$VISUAL`/`$EDITOR`/`vi` on a tmp file; the saved content runs as the next prompt. |
+| `/exit` | Quit. |
+
+### Multi-line input
+
+End a line with a single `\` to continue on the next line (bash-style).
+`\\` is treated as a literal trailing backslash. For longer or paste-heavy
+drafts, use `/edit`.
+
+```
+> please write a function\
+… that takes (a, b, c)\
+… and returns a + b + c
+```
+
+### Hotkeys
+
+`Ctrl+C` aborts the current turn (first press), exits if pressed again
+within 1 second. `Ctrl+D` exits cleanly. Up / down arrows recall past
+prompts (persisted across sessions).
+
+### Session scoping (per-directory)
+
+Sessions are tied to the directory you launched dsc from — that's how
+auto-resume figures out which conversation to bring back.
+
+- Run `dsc` in `~/code/foo` → it auto-resumes the most recent session
+  whose `cwd` is `~/code/foo`. If there isn't one, you start fresh.
+- `cd` into `~/code/bar` and run `dsc` → you get bar's last session,
+  not foo's. Project conversations stay scoped to their project; you
+  can't accidentally bleed astrophysics notes into a CLI refactor.
+- `/clear` starts a brand-new session **for the current cwd**. The old
+  one stays on disk and shows up in `/list` next time you're back.
+- `/list` shows only sessions whose `cwd` matches the current
+  directory. `/resume <#>` resolves indices from that list.
+- `/resume <id>` (or a `/save`'d name) **can** cross cwds — useful
+  if you want to revisit a session from elsewhere; the cwd it was
+  born in stays attached to it.
+- `--no-resume` skips auto-resume entirely and gives you a fresh
+  session this launch.
+
+Each session is a single JSON file under
+`~/.local/share/dsc/sessions/`. Open one in your editor if you want to
+see exactly what got persisted, including any compacted summary and
+the archived messages from `/transcript`.
+
+## Tools the agent can use
+
+| Tool | Approval | Notes |
+|---|---|---|
+| `read_file(path, offset?, limit?)` | none | 2000 lines default; long lines truncated. |
+| `grep(pattern, path?, glob?, case_insensitive?)` | none | ripgrep when available, `grep -rn` fallback. |
+| `glob(pattern, path?)` | none | Node 22+ `fs.glob`, capped at 500. |
+| `web_search(query, count?, freshness?)` | none | Pluggable backends (Brave / Tavily / DuckDuckGo). |
+| `write_file(path, content)` | yes (unless `--yolo`) | Side-by-side diff in the prompt. |
+| `edit_file(path, old_string, new_string, replace_all?)` | yes | Exact substring replace; old_string must be unique unless `replace_all=true`. |
+| `bash(command, description?, timeout_ms?)` | yes | `/bin/sh -c`, output capped at 16 KB. |
+| `web_fetch(url)` | yes | HTML stripped to text, capped at 50 KB. |
+
+Read-only tools never prompt. The rest do unless `--yolo` is on.
+
+## Sessions and history
+
+Each session is a JSON file under `$XDG_DATA_HOME/dsc/sessions/`
+(default `~/.local/share/dsc/sessions/`) keyed by id. It carries:
+
+- `messages` — the active conversation log (sent to the API).
+- `archivedMessages` — older messages that `/compact` has summarized away.
+  Persisted on disk for `/transcript`, never sent to the API.
+- `compaction` — the cumulative summary text and metadata.
+- `stats` — token / cost / tool-call counters.
+- `model` — last selected model.
+
+Saves happen on every `onTurn` callback (after each assistant message,
+after each tool result), with a single-in-flight, coalescing writer —
+so a Ctrl+C / OOM / power loss mid-turn won't cost you the latest
+committed state.
+
+## Compaction
+
+`/compact [N]` summarizes everything before the last `N` user turns,
+stores the summary on the session, archives the original messages, and
+trims `messages` to the kept tail. The summary appears in the dynamic
+suffix of every subsequent system prompt (`Previously in this session:`),
+so the model retains semantic context. Cumulative — re-running `/compact`
+folds the prior summary into the new one.
+
+Auto-compact runs the same routine after any successful turn whose
+estimated context exceeds `DSC_AUTO_COMPACT_AT` tokens (default 50 000;
+set `0` / `off` / `false` to disable).
+
+`/transcript` prints the full conversation, including archived chunks,
+so nothing is lost — just absent from the prompt the model sees.
+
+## Audit log
+
+Every tool execution (including rejected ones) writes one JSONL line to
+`$XDG_STATE_HOME/dsc/audit.log` (default `~/.local/state/dsc/audit.log`).
+Each line carries `ts`, `session`, `cwd`, `tool`, `approved`, plus
+tool-specific fields:
+
+```json
+{"ts":"2026-05-09T15:32:01Z","session":"…","cwd":"/home/dann/code/dsc","tool":"bash","approved":true,"command":"npm test","exit":0,"stdout_bytes":4012,"stderr_bytes":0}
+```
+
+Useful greps:
+
+```sh
+# every bash command this week
+jq 'select(.tool=="bash") | "\(.ts) \(.command)"' ~/.local/state/dsc/audit.log
+
+# things rejected at approval
+jq 'select(.approved==false)' ~/.local/state/dsc/audit.log
+
+# files written by a specific session
+jq 'select(.session=="abc1234" and .tool=="write_file") | .path' \
+   ~/.local/state/dsc/audit.log
+```
+
+Disable with `DSC_NO_AUDIT=1`. There's no rotation — at gigabyte scale
+you'll want to truncate it yourself.
+
+## File locations
+
+| Path | What |
+|---|---|
+| `~/.config/deepseek/deepseek.json` | API key (and search-provider keys). 0600. |
+| `~/.local/share/dsc/sessions/<id>.json` | One file per session. |
+| `~/.local/state/dsc/history` | Up/down arrow recall (1000-line cap). |
+| `~/.local/state/dsc/audit.log` | JSONL, append-only. |
+| `/tmp/dsc-edit-*/prompt.md` | Transient; created by `/edit`, removed on close. |
+| `<repo>/dist/` | Compiled output (only used as a fallback for the global shim). |
+
+XDG variables observed: `XDG_CONFIG_HOME`, `XDG_STATE_HOME`, `XDG_DATA_HOME`.
+
+## Environment variables
+
+| Var | Default | Purpose |
+|---|---|---|
+| `DEEPSEEK_API_KEY` | (read from config file) | Overrides the `api_key` in `deepseek.json`. |
+| `DSC_AUTO_COMPACT_AT` | `50000` | Token threshold for auto-compact. `0`/`off`/`false` disables. |
+| `DSC_NO_AUDIT` | (off) | `1` disables the JSONL audit log. |
+| `DSC_SEARCH_PROVIDER` | (config or `ddg`) | `brave`, `tavily`, or `ddg`. |
+| `BRAVE_API_KEY` | (config) | Brave Search key. |
+| `TAVILY_API_KEY` | (config) | Tavily key. |
+| `VISUAL` / `EDITOR` | (vi) | Used by `/edit`. |
+| `XDG_CONFIG_HOME` | `~/.config` | Config root. |
+| `XDG_STATE_HOME` | `~/.local/state` | State root. |
+| `XDG_DATA_HOME` | `~/.local/share` | Data root. |
+
+## Search providers
+
+Pick at runtime with `DSC_SEARCH_PROVIDER`:
+
+- **brave** — [api-dashboard.search.brave.com](https://api-dashboard.search.brave.com), 2000 free queries/month. Recommended.
+- **tavily** — [tavily.com](https://tavily.com), 1000 free/month, agent-tuned snippets.
+- **ddg** — DuckDuckGo HTML scrape, no key, brittle.
+
+Per-provider keys live in the config:
+
+```jsonc
+{
+  "api_key": "sk-...",
+  "search": {
+    "provider": "brave",
+    "brave": { "api_key": "BSA..." }
+  }
+}
+```
+
+`{PROVIDER}_API_KEY` env var (e.g. `BRAVE_API_KEY`) overrides the
+file value.
+
+## Packaging and distribution
+
+For local global install (any platform with Node 22+):
+
+```sh
+npm run package              # produces pkg/<name>-<version>.tgz
+scripts/install.sh           # linux / macOS  — wraps `npm install -g pkg/*.tgz`
+.\scripts\install.ps1        # Windows PowerShell — same idea
+```
+
+The build is driven by the `prepack` lifecycle hook (`scripts/build.mjs`),
+which wipes `dist/` before recompiling. That keeps stale artifacts (e.g.
+leftover from a branch switch) out of the tarball whether you ran
+`npm pack`, `npm publish`, or `npm run package`.
+
+What ships is controlled by the `files` field in `package.json` (currently
+`bin/`, `dist/`, `README.md`, `LICENSE`). Source TypeScript and devDeps are
+deliberately excluded.
+
+### Publishing to npm
+
+The package is configured to publish as `@este.systems/dsc` with public
+access. To release:
+
+```sh
+# 1. Bump the version (semver). For a pre-1.0 patch:
+npm version patch                       # → 0.1.1, also creates a git tag
+
+# 2. Make sure you're logged in to npm:
+npm whoami                              # should print your username
+npm login                               # if not
+
+# 3. (Optional) preview the tarball:
+npm pack --dry-run
+
+# 4. Publish:
+npm publish                             # respects publishConfig.access=public
+
+# 5. Push the version-bump commit and tag:
+git push --follow-tags
+```
+
+Notes:
+
+- The package name is **scoped** (`@este.systems/dsc`), so `npm publish`
+  defaults to private. `publishConfig.access = "public"` in `package.json`
+  overrides that. Don't drop it.
+- npm now nudges hard for **2FA**. Enable with
+  `npm profile enable-2fa auth-and-writes`. You'll be asked for an OTP on
+  every publish.
+- Once published, anyone can install with
+  `npm install -g @este.systems/dsc`. The CLI binary is still just `dsc`.
+- After publish, the `pkg/*.tgz` produced locally is identical to what
+  you uploaded — useful for offline installs (`scripts/install.sh`).
+
+## Development
+
+```sh
+npm run dev                  # tsx src/index.ts
+npm run typecheck            # tsc --noEmit
+npm run build                # compiles to dist/
+npm run package              # build + npm pack into pkg/
+```
+
+Source layout:
+
+```
+src/
+  index.ts          # REPL, slash commands, signal handling
+  agent.ts          # tool-call loop, status formatting, repair logic
+  api.ts            # DeepSeek client, retry/abort, prompt cache rates
+  tools.ts          # tool schemas + executors (read/write/edit/bash/grep/glob/web_*)
+  approval.ts       # confirmWrite/Edit/Bash/Fetch
+  audit.ts          # JSONL audit logger
+  search.ts         # Brave / Tavily / DDG dispatch
+  compact.ts        # /compact summarization routine
+  history.ts        # session save/load/list/migrate-legacy
+  repl_history.ts   # ~/.local/state/dsc/history reader/writer
+  markdown.ts       # streaming markdown→ANSI renderer (incl. tables, HR, LaTeX→Unicode)
+  ui.ts             # Spinner with stall detection; one-line StatusBar
+  prompt.ts         # SYSTEM_PROMPT + buildSystemPrompt
+```
+
+The `ink-port` branch is a parked experiment — a React-based ink TUI
+shell. `main` deliberately stays a plain REPL so output remains
+selectable.

package/bin/dsc.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+// Resolve the package root from this file's location. With `npm link` the
+// global symlink resolves through to the real repo, so this points at the
+// editable source — no rebuild needed.
+const here = dirname(fileURLToPath(import.meta.url));
+const pkgRoot = dirname(here);
+const tsxBin = join(pkgRoot, "node_modules", ".bin", "tsx");
+const srcEntry = join(pkgRoot, "src", "index.ts");
+const distEntry = join(pkgRoot, "dist", "index.js");
+
+if (existsSync(tsxBin) && existsSync(srcEntry)) {
+  // Dev: run TS sources directly. Live changes pick up on next launch.
+  const child = spawn(tsxBin, [srcEntry, ...process.argv.slice(2)], {
+    stdio: "inherit",
+  });
+  child.on("exit", (code, signal) => {
+    if (signal) process.kill(process.pid, signal);
+    else process.exit(code ?? 0);
+  });
+} else {
+  // Fallback: production-style install without devDeps. Use the compiled
+  // output instead. Run `npm run build` to refresh `dist/`.
+  await import(distEntry);
+}