dalang-cli 0.0.0-stage → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Fauzan Azmi
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,150 @@
1
- # Temporary Holding Version
1
+ # DALANG
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ > One goal in, a running app out. A local web tool that orchestrates Claude Code, Codex, and Antigravity CLI as a small team.
4
+
5
+ **Status: v0.6.0 (UI revamp) is released on npm as `dalang-cli` and verified on Linux: 4-screen first-run wizard, left sidebar shell with 5-step guided project stepper (`Discuss -> Brief -> Plan -> Work -> Review & merge`) and `"Next step"` card, `Config` with 6 sidebar tabs + dedicated `Statistics` page, Indonesian and English (`ID | EN`) across both the UI and Lead/Reviewer output, Light/Dark/Follow-system theme toggle, archival-derived wayang kulit & redrawn gunungan artwork (`CREDITS.md`), lit kelir Work stage with factual Activity Feed and pause/reduced-motion controls, and non-blocking new-version notice (`GET /api/update-status` and `dalang doctor`). Builds on all v0.5 features (`npx dalang-cli`, `dalang doctor`, multiple accounts per provider, rich CLI model details, token/cost stats, hybrid hidden checkpoints, push & GitHub PR after merge, Linux `bwrap` and macOS `sandbox-exec`). Next: v0.7 (session modes: Ask, Quick, Full). See [docs/PRD.md](docs/PRD.md) for the full roadmap.**
6
+
7
+ DALANG is named after the traditional Javanese puppeteer who directs the whole show. The name is also an acronym for the workflow:
8
+
9
+ **D**iscuss · **A**gree · **L**ist · **A**ssign · **N**avigate · **G**uard
10
+
11
+ ## What it does
12
+
13
+ You write one general goal in a chat. A Lead agent discusses it with you, confirms the scope, and breaks it into small tasks. A dispatcher then hands each task to an agent based on role, subscription, and the model you configured. A reviewer checks the result before anything is merged.
14
+
15
+ Everything runs on your machine and uses the official CLI logins you already have. No API keys, no extra tokens. You only step in at two gates: approving the brief and approving the merge.
16
+
17
+ | Step | What happens |
18
+ | --- | --- |
19
+ | 1 Discuss | The Lead asks structured questions and clarifies the goal |
20
+ | 2 Brief | The Lead writes a brief. You edit and approve it (gate 1) |
21
+ | 3 Plan | The Lead splits the brief into milestones and tasks on a kanban board or topological dependency graph |
22
+ | 4 Work | The dispatcher groups tasks into waves, flags file overlaps, and routes each task with proactive quota fallback. Non-overlapping agents run concurrently in isolated git worktrees within per-provider limits, shown as a wayang stage with a factual activity feed, live logs, and checkpoints |
23
+ | 5 Review and merge | A reviewer runs the verify command and writes a review; you inspect diffs, approve merge onto main, or reject (gate 2), followed by post-merge integration tests, push, and pull request |
24
+
25
+ A "Next step" card above the steps always says what to do now. The UI is available in English and Indonesian (the Lead and reviewer write in the language you pick), with a light/dark theme toggle.
26
+
27
+ ## Why
28
+
29
+ Developers with several coding-agent subscriptions run them by hand, one after another: plan in one tool, code in another, review in a third. That means manual handoffs, serial babysitting, uneven quota use, and no audit trail. DALANG automates the handoffs, spreads work across subscriptions, falls back when one hits a limit, and keeps every artifact (brief, plan, task, log, review) in your repo.
30
+
31
+ ## Design at a glance
32
+
33
+ - **Local only.** The server binds to `127.0.0.1`. Not a SaaS, not multi-user.
34
+ - **One global instance, many projects.** Quota is shared across projects, so limits and fallback must see all of them. Global state lives in `~/.dalang/` (SQLite); per-project artifacts live in `<repo>/.dalang/` and are versioned in git.
35
+ - **Official CLIs only.** DALANG spawns the `claude`, `codex`, and `agy` binaries. It never calls model APIs directly and never reuses their OAuth tokens.
36
+ - **Provider and model are separate settings.** Each agent profile sets provider, model, effort, role prompt, permission mode, timeouts, and parallelism. Routing rules map task role and complexity to a profile, with a fallback.
37
+ - **Decisions come from files, not stdout.** Agents write JSON to `.dalang/`, validated with Zod. Invalid output is sent back for up to two retries.
38
+ - **Sandboxed runs (Linux & macOS).** Each CLI runs inside `bwrap` (Linux) or `sandbox-exec` (macOS) so it can only write inside the project folder and its own config dir, with credential folders such as `~/.ssh` hidden. Windows runs through WSL 2 in v0.5. See [docs/SANDBOX.md](docs/SANDBOX.md).
39
+
40
+ Stack: TypeScript 7, Node.js 26 LTS, Fastify 5 + WebSocket, React 19 + Vite 8 + shadcn/ui on Tailwind 4, SQLite (better-sqlite3) + Drizzle, Zod 4, simple-git. The UI follows [docs/DESIGN.md](docs/DESIGN.md).
41
+
42
+ ## Repository layout
43
+
44
+ | Package | Role |
45
+ | --- | --- |
46
+ | `packages/shared` | Zod schemas and DTO types shared by the server and the UI |
47
+ | `packages/core` | SQLite schema, provider adapters (`claude`, `codex`, `agy`), sandbox wrapper, Lead and execution services, git checkpoints |
48
+ | `packages/server` | Fastify API and WebSocket event stream, bound to loopback |
49
+ | `packages/web` | React UI (shadcn/ui on Tailwind, styled by `docs/DESIGN.md`) |
50
+ | `packages/cli` | The `dalang` command that starts the server and opens the browser |
51
+
52
+ ## Run it
53
+
54
+ Requires Node.js 24+ (Node.js 26 LTS recommended; checked on 24 and 26), git, and at least one logged-in CLI (`claude`, `codex`, or `agy`). On Linux, install `bubblewrap` (and `xdg-dbus-proxy` if you use agy); on macOS `/usr/bin/sandbox-exec` is used automatically; on Windows run inside WSL 2.
55
+
56
+ ```bash
57
+ # Check environment, sandbox, and CLI logins
58
+ npx dalang-cli doctor
59
+
60
+ # Start the local server (http://127.0.0.1:4173) and open the browser
61
+ npx dalang-cli
62
+ ```
63
+
64
+ To update, stop the server and run `npx dalang-cli@latest` (or `npm install -g dalang-cli@latest` if installed globally). Your data is kept; see [Updating](docs/INSTALL.md#updating).
65
+
66
+ Or run from a local clone:
67
+
68
+ ```bash
69
+ pnpm install
70
+ pnpm build
71
+ pnpm --filter dalang-cli doctor
72
+ pnpm start # serves http://127.0.0.1:4173 and opens the browser
73
+ ```
74
+
75
+ `pnpm test` runs the unit, replay, browser E2E, and CLI doctor tests without spending model quota. See [docs/INSTALL.md](docs/INSTALL.md) for full platform setup.
76
+
77
+ ### A first run
78
+
79
+ 0. **Wizard (empty install only):** a four-screen guide covers how DALANG works, which agent CLIs are ready, a recommended team, and your first project. Skip it any time; reopen it from Config → About.
80
+ 1. **Projects:** create a new folder (DALANG runs `git init`) or open an existing repo.
81
+ 2. **Discuss, Brief:** describe a goal, answer the Lead's question cards, press "Enough, write the brief", edit the brief, and approve it.
82
+ 3. **Plan:** generate the plan, adjust tasks on the kanban board, and approve the plan.
83
+ 4. **Work:** inspect the dependency graph, file overlaps, and routed profiles, then start the parallel run. Watch the stage and concurrent worktree logs, stop individual tasks or the whole queue, retry or resume a session, or roll back to a checkpoint.
84
+ 5. **Review and merge:** read the review and the diff, then approve the merge or reject with a note.
85
+
86
+ Everything DALANG writes for a project lives in `<repo>/.dalang/` (brief, plan, per-task `result.json`, logs). Global state lives in `~/.dalang/`.
87
+
88
+ ## CLI validation (18 Nov 2026)
89
+
90
+ The core assumptions were tested on Linux with Claude Code, Codex 0.169.0, and Antigravity CLI (`agy`) 1.5.10, all headless without a TTY.
91
+
92
+ | Check | Claude Code | Codex | agy |
93
+ | --- | --- | --- | --- |
94
+ | Headless run with JSON output | yes | yes | yes |
95
+ | Write files into `.dalang/` | yes | yes | yes |
96
+ | Resume a session across turns | yes | yes | yes |
97
+ | Output conforming to a simple JSON schema (not used by DALANG, see PRD) | yes | yes | yes |
98
+ | Refuses writes outside the project | yes | yes (but `/tmp` is writable) | **no** |
99
+ | Refuses outside writes when wrapped in `bwrap` | yes | yes | yes |
100
+ | Usage and limits readable before a run | `/usage` | `account/rateLimits/read` via `codex app-server` | `/usage` |
101
+
102
+ Key findings: `agy` writes outside the workspace even with its sandbox flag, so every adapter is wrapped in `bwrap`. Codex hangs unless stdin is closed, and its own sandbox cannot run inside `bwrap`, so DALANG lets `bwrap` be the boundary. `node-pty` is not required. See the PRD for the full list, including what is still untested (macOS and Windows, prompt-injection attacks on the guard prompt, and a real quota-limit reroute).
103
+
104
+ ## Verified with real models
105
+
106
+ Run on 18 and 19 Nov 2026 on Linux, through the HTTP API and the real sandbox, one run per scenario (so it shows the flow works, not how often).
107
+
108
+ | Phase | Scenario | Result |
109
+ | --- | --- | --- |
110
+ | v0.1 | Goal to approved brief and plan, one project per Lead provider | 3 of 3 valid, in 117 to 361 seconds |
111
+ | v0.2 | Notes REST API planned as 6 tasks and executed on Claude Code, Codex, and agy | 6 of 6 done in about 9.5 minutes, 27 of 27 tests passing, every endpoint checked by hand |
112
+ | v0.2 | Codex hit "Selected model is at capacity" mid-run | Idle timeout, then the backup profile finished the task |
113
+ | v0.3 | Five small projects (15 tasks), each task executed, verified, reviewed by another provider, diffed, and merged | 15 of 15 passed review within 2 rounds (13 on round 1, 2 on round 2), 96 of 96 tests passing |
114
+ | v0.4 | Two independent tasks on Claude Code, each in its own worktree | Both ran at the same time, passed review on round 1, merged cleanly, 6 of 6 tests passing |
115
+
116
+ ## Known limits
117
+
118
+ - **Linux only for confinement.** `bwrap` keeps agents inside the project folder and hides credential folders. macOS and Windows have no sandbox yet, so execution there needs an explicit opt-in.
119
+ - **agy can read your desktop keyring.** It signs in through the Secret Service, and the filtered bus it gets (`xdg-dbus-proxy`, needed along with a desktop session) allows that whole service, so an agy run can read every secret stored there. Claude Code and Codex runs cannot. This is **off by default**: until you tick "Allow Antigravity to read the desktop keyring" in Config → Security, a task routed to agy runs on its backup profile instead, and agy cannot be a Lead inside the sandbox. Provider state folders (`~/.claude`, `~/.codex`, `~/.gemini`) stay writable for token refresh, which is listed in the PRD risks.
120
+ - **The review sample is small.** 15 tasks in five small projects passed review; larger code bases and the agy reviewer are untested. Windows and macOS hosts are untested. Parallel worktrees were tried once with real Claude Code (two tasks); a real quota-limit reroute has not been observed (verified via scripted runner tests).
121
+ - **Scope is checked after the fact.** Edits outside a task's `files_allowed` are not blocked while the agent works, but they fail the review (whatever the reviewer says), so the task cannot be merged without your override. Tasks with overlapping `files_allowed` are serialized rather than run concurrently.
122
+
123
+ ## Roadmap
124
+
125
+ | Phase | Scope | Status |
126
+ | --- | --- | --- |
127
+ | v0.1 Rembuk | Projects, Lead chat, brief, plan and kanban, provider status page | Released |
128
+ | v0.2 Jalan | Routing and dispatch, sequential execution, live logs, git checkpoints, stop, retry, resume, rollback | Released |
129
+ | v0.3 Kawal | Reviewer and fix loop, diff view, approve merge, post-merge integration, profiles and routing in UI | Released |
130
+ | v0.4 Paralel | Worktree per task, dependency graph, per-provider limits, quota fallback, usage stats | Released (one real two-task parallel run; quota reroute scripted only) |
131
+ | v0.5 | `npx dalang-cli` and `dalang doctor`, several accounts per provider, model details, token & cost statistics, replay & browser tests, hidden checkpoint refs, macOS sandbox, push and pull request, docs | Released |
132
+ | v0.6 | UI revamp: first-run wizard, guided five-step flow, wayang stage during work, Config page, Indonesian and English, new-version notice | Released |
133
+ | v0.7 | Session modes: a project opens into a chat; switch to Quick (small fix, no brief) or Full (five steps) from the composer; sessions saved per project and reopenable like a chat | Planned |
134
+ | v0.8 | Agent delegation: a running agent splits its task into subtasks on other profiles over MCP | Planned |
135
+ | v0.9 | Session protocols, steering, context handoff on fallback, native Windows | Planned |
136
+ | v0.10 | Scheduled and webhook runs, outside agents over MCP | Planned |
137
+
138
+ ## Documentation
139
+
140
+ - [Installation & platform setup](docs/INSTALL.md)
141
+ - [Providers, models & multi-account setup](docs/PROVIDERS.md)
142
+ - [Sandbox & security model](docs/SANDBOX.md)
143
+ - [Troubleshooting](docs/TROUBLESHOOTING.md)
144
+ - [Product requirements](docs/PRD.md)
145
+ - [Design direction](docs/DESIGN.md)
146
+ - [Changelog](CHANGELOG.md)
147
+
148
+ ## License
149
+
150
+ [MIT](LICENSE)
package/bin/dalang.js ADDED
@@ -0,0 +1,7 @@
1
+ #!/usr/bin/env node
2
+ import { main } from '../bundle/cli.js';
3
+
4
+ main().catch((err) => {
5
+ console.error(err instanceof Error ? err.message : String(err));
6
+ process.exit(1);
7
+ });