test: validate PR #300 CI

.github/workflows/ci.yml

@@ -6,6 +6,9 @@ on:
       - main
   pull_request:
 
+permissions:
+  contents: read
+
 concurrency:
   group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
   cancel-in-progress: true
@@ -24,22 +27,21 @@ jobs:
           - windows-latest
 
     env:
-      DEVSPACE_ALLOWED_ROOTS: ${{ github.workspace }}
       DEVSPACE_OAUTH_OWNER_TOKEN: ci-owner-token-that-is-long-enough
-      DEVSPACE_PUBLIC_BASE_URL: http://127.0.0.1:7676
 
     steps:
       - name: Checkout
         uses: actions/checkout@v4
 
-      - name: Setup Node
-        uses: actions/setup-node@v4
+      - name: Setup pnpm and Node
+        uses: pnpm/setup@84cb39b217b10273981911c288cd62326dc7c6d2 # v2
         with:
-          node-version: 22
-          cache: npm
+          runtime: node@22
+          cache: true
+          install: false
 
       - name: Install dependencies
-        run: npm ci
+        run: pnpm install --frozen-lockfile
 
       - name: Install Pi sandbox dependencies
         if: matrix.os == 'ubuntu-latest'
@@ -51,15 +53,18 @@ jobs:
           fi
 
       - name: Typecheck
-        run: npm run typecheck
+        run: pnpm typecheck
 
       - name: Test
         env:
           DEVSPACE_REQUIRE_PI_SANDBOX: ${{ matrix.os == 'ubuntu-latest' && '1' || '0' }}
-        run: npm test
+        run: pnpm test
+
+      - name: Package install smoke test
+        run: pnpm test:package-install
 
       - name: Build
-        run: npm run build
+        run: pnpm build
 
       - name: Doctor
         run: node dist/cli.js doctor

README.md

@@ -246,11 +246,14 @@ This year, I began my journey to build a one-person, multi-agent company capable
 
 For working on DevSpace itself:
 
+Install pnpm 11.25.0, the version pinned in `package.json`, with
+`npm install --global pnpm@11.25.0`, then:
+
 ```bash
-npm install --include=dev
-npm run dev
-npm run typecheck
-npm test
-npm run build
-npm run start
+pnpm install --frozen-lockfile
+pnpm dev
+pnpm typecheck
+pnpm test
+pnpm build
+pnpm start
 ```

bin/devspace-agentd.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runEntrypoint } from "./run-entrypoint.js";
+
+await runEntrypoint("../src/local-agent-daemon-main.ts", "../dist/local-agent-daemon-main.js");

bin/devspace.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runEntrypoint } from "./run-entrypoint.js";
+
+await runEntrypoint("../src/cli.ts", "../dist/cli.js");

bin/run-entrypoint.js

@@ -0,0 +1,20 @@
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+export async function runEntrypoint(sourcePath, distPath) {
+  const sourceUrl = new URL(sourcePath, import.meta.url);
+  if (existsSync(fileURLToPath(sourceUrl))) {
+    try {
+      await import("tsx/esm");
+    } catch (error) {
+      throw new Error(
+        "DevSpace source checkout detected, but tsx is unavailable. Run `pnpm install` in the checkout; refusing to fall back to potentially stale dist output.",
+        { cause: error },
+      );
+    }
+    await import(sourceUrl.href);
+    return;
+  }
+
+  await import(new URL(distPath, import.meta.url).href);
+}

docs/artifact-exchange.md

@@ -1,7 +1,8 @@
 # Download a native file
 
 DevSpace can save a file attached or generated by an MCP host, such as ChatGPT,
-directly into an open workspace. Enable the tool with `DEVSPACE_ARTIFACTS=1`.
+directly into an open workspace. Enable the tool with
+`artifacts.enabled` in `~/.devspace/config.jsonc`.
 
 ## Workflow
 
@@ -36,7 +37,7 @@ file-object shape, trusted OpenAI download hosts, and redirects before streaming
 Malformed references, unknown fields, absolute paths, traversal, and symlinked
 parents are rejected.
 
-Downloads are streamed under `DEVSPACE_ARTIFACT_MAX_FILE_BYTES` and published as
+Downloads are streamed under `artifacts.maxFileBytes` and published as
 owner-only files without overwriting an existing destination. The tool is
 currently available on Linux. It is not registered on macOS, Windows, or BSD
 because Node.js does not expose the required descriptor-relative filesystem

docs/chatgpt-coding-workflow.md

@@ -117,8 +117,8 @@ DevSpace discovers standard Agent Skills from:
 It also keeps compatibility with:
 
 - the bundled `subagents` skill when Subagents are enabled, unless `~/.devspace/skills/subagents/SKILL.md` exists
-- `DEVSPACE_AGENT_DIR/skills`, defaulting to `~/.codex/skills`
-- additional paths from `DEVSPACE_SKILL_PATHS`
+- `skills.agentDir/skills`, defaulting to `~/.codex/skills`
+- additional paths from `skills.paths`
 
 When Subagents are enabled, DevSpace discovers agent profiles
 from `~/.devspace/agents/*.md` and project `.devspace/agents/*.md`.
@@ -130,7 +130,7 @@ Example profiles are packaged under `examples/agents/` for users who want
 starter templates. Copy or adapt them into one of the active profile directories
 before use.
 
-Legacy project paths such as `.pi/skills` can be added through `DEVSPACE_SKILL_PATHS` when needed.
+Legacy project paths such as `.pi/skills` can be added to `skills.paths` when needed.
 
 When `open_workspace` returns matching skills, the model should read the
 advertised `SKILL.md` before following that skill.
@@ -140,8 +140,8 @@ Skill paths may be outside the workspace. DevSpace only permits reading:
 - advertised `SKILL.md` files
 - files under a skill directory after that skill's `SKILL.md` has been read
 
-Set `DEVSPACE_SKILLS=0` to hide skills from workspace output. Enable Subagents
-and choose providers through `devspace init` or the persisted provider
+Set `skills.enabled` to `false` to hide skills from workspace output. Enable
+Subagents and choose providers through `devspace init` or the persisted provider
 configuration. The bundled `subagents` skill teaches the minimal
 `devspace agents targets`, `devspace agents ls`, `devspace agents run`,
 `devspace agents continue`, and `devspace agents show` workflow. The catalog
@@ -150,48 +150,57 @@ sessions for that workspace.
 
 ## Tool Names
 
-DevSpace exposes these tool names:
+The Claude surface exposes these tool names:
 
 - `open_workspace`
 - `read`
 - `write`
 - `edit`
 - `bash`
+- `show_changes`
 
-By default, DevSpace also runs in `DEVSPACE_TOOL_MODE=minimal`, so dedicated
-`grep`, `glob`, and `ls` tools are hidden. Use `bash` with command-line tools
-such as `rg`, `find`, and `ls` for search and directory inspection.
-
-Use `DEVSPACE_TOOL_MODE=full` to restore dedicated search and directory tools.
-
-The experimental Codex-style surface is enabled with
-`DEVSPACE_TOOL_MODE=codex`. It exposes:
+DevSpace uses the Codex-style surface by default. It exposes:
 
 - `open_workspace`
 - `read`
 - `apply_patch`
 - `exec_command`
 - `write_stdin`
+- `show_changes`
 
-In this mode, `write`, `edit`, `bash`, `grep`, `glob`, and `ls` are not
-registered. `exec_command` returns a process session ID when a command is still
+In this mode, `write`, `edit`, and `bash` are not registered. `exec_command`
+returns a process session ID when a command is still
 running after its yield window. Use `write_stdin` to poll it, send input, resize
 a PTY, or send Ctrl-C. Set `tty: true` only for commands that need a terminal.
 
-## Show Changes
-
-By default, `DEVSPACE_WIDGETS=full`.
-
-In that mode, DevSpace attaches widget UI to the exposed workspace, file, edit,
-and shell tools. The aggregate `show_changes` tool is not exposed by default.
+Set `tools.mode` to `claude` in `~/.devspace/config.jsonc` to expose `write`,
+`edit`, and `bash` instead of the Codex mutation and command tools. Dedicated
+MCP tools for `grep`, `glob`, and `ls` are not registered in either mode; use
+the configured shell tool with command-line tools such as `rg`, `find`, and
+`ls`.
 
-Use `DEVSPACE_WIDGETS=off` to disable widget UI, or `DEVSPACE_WIDGETS=changes`
-to expose the aggregate show-changes flow.
+## Show Changes
 
-When `show_changes` is exposed, call it exactly once after the final file
-modification in any turn that changes files. It shows the combined changes for
-that turn and advances the review point automatically. Reusing a workspace does
-not change this workflow.
+DevSpace exposes `show_changes` in both tool modes and attaches widget UI only
+to `open_workspace` and `show_changes`. Reads, edits, and commands return normal
+MCP results without creating an iframe for each call. Set `ui.enabled` to
+`false` in `~/.devspace/config.jsonc` to disable UI metadata while keeping the
+aggregate review tool available.
+
+Call `show_changes` exactly once after the final file modification in any turn
+that changes files. It shows the combined changes for that turn and advances
+the review point automatically. Reusing a workspace does not change this
+workflow.
+
+The model-facing result stays compact: DevSpace returns the workspace ID, a
+Git-backed `reviewRef`, and the summary text. MCP Apps hosts receive the full
+file list and patch in result metadata for immediate rendering. If a host later
+restores only the structured result, the review card can reopen that exact
+`reviewRef` from DevSpace's Git review history without advancing the current
+review point.
+
+For local inspection, run `devspace show-changes <review-ref>`. Add `--json` to
+include the parsed summary, file list, and patch.
 
 ## Shell Use