datagrok-tools 6.0.6 → 6.0.8

package/.devcontainer/PACKAGES_DEV.md

@@ -2,36 +2,37 @@
 
 Isolated environment for JS/TS package development against a running Datagrok instance.
 All images are pre-built on Docker Hub — no local build step needed. Install `datagrok-tools`
-globally and run `grok claude` from any git repo.
+globally and run `grok claude` from any directory.
 
 ## Quick start
 
 ```bash
 npm i -g datagrok-tools        # one-time install
-export ANTHROPIC_API_KEY=...   # or set in shell profile
 
 # From any package directory:
-grok claude
-
-# With options:
-grok claude --version 1.22.0 --profile full --task GROK-123
-
-# Stop containers:
-grok claude --stop --task GROK-123
+grok claude GROK-12345                        # start working on a task
+grok claude GROK-12345 --version 1.22.0       # pin Datagrok version
+grok claude GROK-12345 --profile full --keep  # all services, keep running
+grok claude GROK-12345 --prompt "fix the bug" # one-shot command
+grok claude GROK-12345 --in-place             # use current directory (no worktree)
+grok claude destroy GROK-12345                # tear down a task
+grok claude destroy-all                       # tear down everything
 ```
 
-The `grok claude` command is fully self-contained — the compose configuration is
-embedded in the CLI, all container images are pulled from Docker Hub (`datagrok/tools-dev`,
-`datagrok/datagrok`, etc.). No files to copy, no Dockerfile to build.
-See `grok claude --help` for all options.
+Authentication: Claude Code credentials are copied from the host `~/.claude/` into the
+container on startup. Alternatively, set `ANTHROPIC_API_KEY` in the environment.
+
+**Project name restrictions:** `master` and `main` are rejected.
 
 ### What it does
 
-1. Generates a `docker-compose.yaml` and `.env` in a temp directory
-2. Runs `docker compose up -d --wait` (pulls pre-built images)
-3. Waits for Datagrok to be healthy
-4. Launches `claude --dangerously-skip-permissions` inside the `tools-dev` container
-5. On exit, stops containers (unless `--keep`)
+1. Creates a git worktree at `~/pkg-worktrees/<project>` (unless `--in-place` or not in a git repo)
+2. Generates `docker-compose.yaml`, `.env`, and optional `docker-compose.override.yaml` in `$TMPDIR/dg-pkg-<project>`
+3. Runs `docker compose up -d --wait` (pulls pre-built images from Docker Hub)
+4. Copies Claude credentials into the container and fixes ownership
+5. Detects working directory based on repo type (see below)
+6. Launches `claude --dangerously-skip-permissions` inside the `tools-dev` container
+7. On exit, stops containers (unless `--keep`)
 
 ### Manual setup
 
@@ -39,126 +40,162 @@ For manual setup or customization, use the `docker-compose.yaml` in this directo
 directly. The `Dockerfile.pkg_dev` and `entrypoint.sh` are the build recipe for the
 `datagrok/tools-dev` Docker Hub image — end users don't need them.
 
-## What you can do
-
-| Workflow | How it works |
-|----------|-------------|
-| **Develop packages (public repo)** | Mount public repo worktree as `/workspace`. Agent reads js-api source, help docs, ApiSamples, and CLAUDE.md skills directly. |
-| **Develop packages (separate repo)** | Mount your repo as `/workspace`. The public repo is auto-cloned to `/workspace/public` on first start, branch matching `DG_VERSION`. |
-| **Learn from examples** | Agent reads `packages/ApiSamples/scripts/` for runnable code samples and `help/develop/` for guides. |
-| **Search Jira and GitHub** | MCP plugins for Atlassian Jira and GitHub — agent searches for similar issues, reads context, updates status. |
-| **Write and run tests** | Playwright for browser automation, `grok test` for Puppeteer-based package tests, Chrome remote debugging. |
-| **Publish packages** | `grok publish` to the local Datagrok instance or any external server. Agent handles build + publish. |
-| **Manage the Datagrok stand** | Agent changes `DG_VERSION`, pulls new images, resets DB, redeploys — all from inside the container via Docker socket. |
-| **Interactive setup** | Agent asks the user for tokens, auth keys, server URLs via Claude Code prompts. No pre-configuration required. |
-
 ## Architecture
 
 ```
 Host machine
 ┌──────────────────────────────────────────────────────────────────┐
-│  Worktree: ~/pkg-worktrees/TASK-123/                            │
-│    └── public/ (auto-cloned if workspace is not public repo)    │
-│                                                                  │
-│  Docker network: dg-pkg-TASK-123-net                             │
+│  Docker network: dg-pkg-<project>-net                            │
 │  ┌────────────────────────────────────────────────────────────┐  │
-│  │  datagrok    (datagrok/datagrok:${VERSION})    → :8080     │  │
-│  │  postgres    (pgvector/pgvector:pg17)                      │  │
-│  │  rabbitmq    (rabbitmq:4.0.5-management)                   │  │
-│  │  grok_pipe   (datagrok/grok_pipe:${VERSION})               │  │
-│  │  grok_connect, grok_spawner, jkg (optional profiles)       │  │
-│  │  world, test_db, northwind (optional demo DBs)             │  │
-│  │                                                             │  │
-│  │  tools-dev     (datagrok/tools-dev:latest)                     │  │
-│  │    ├── /workspace          ← bind mount of worktree        │  │
-│  │    ├── /var/run/docker.sock ← host Docker for stand mgmt   │  │
-│  │    ├── ~/.claude/          ← bind mount from host          │  │
+│  │  datagrok     (datagrok/datagrok:${VERSION})   → :${PORT} │  │
+│  │  postgres     (pgvector/pgvector:pg17)                     │  │
+│  │  rabbitmq     (rabbitmq:4.0.5-management)                  │  │
+│  │  grok_pipe    (datagrok/grok_pipe:latest)                  │  │
+│  │  grok_connect (datagrok/grok_connect:latest)               │  │
+│  │  grok_spawner, jkg          (optional profiles)            │  │
+│  │  world, test_db, northwind  (optional demo DBs)            │  │
+│  │                                                            │  │
+│  │  tools-dev  (datagrok/tools-dev:latest, runs as root)      │  │
+│  │    ├── /workspace/repo       ← bind mount of worktree     │  │
+│  │    ├── /workspace/datagrok/  ← sparse clone of public repo │  │
+│  │    │   ├── .claude/, CLAUDE.md                             │  │
+│  │    │   ├── js-api/                                         │  │
+│  │    │   ├── libraries/                                      │  │
+│  │    │   └── packages/                                       │  │
+│  │    │       ├── ApiSamples/   ← checked out                 │  │
+│  │    │       └── <folder>/     ← bind mount of user's repo   │  │
+│  │    ├── /var/run/docker.sock  ← host Docker for stand mgmt  │  │
+│  │    ├── entrypoint.sh         ← bind-mounted from tools/    │  │
 │  │    ├── Claude Code + MCP plugins (Jira, GitHub)            │  │
 │  │    ├── Playwright + Chrome for testing                     │  │
 │  │    └── grok CLI for build/publish/test                     │  │
 │  └────────────────────────────────────────────────────────────┘  │
-│                                                                  │
-│  Host browser → http://localhost:8080 (Datagrok UI)              │
-│               → chrome://inspect → localhost:9222 (Debug)        │
-└──────────────────────────────────────────────────────────────────┘
+│                                                                   │
+│  Host browser → http://localhost:${PORT} (Datagrok UI)            │
+│               → chrome://inspect → localhost:9222 (Debug)         │
+└───────────────────────────────────────────────────────────────────┘
 ```
 
-## docker-compose.yaml
+## Working directory detection
 
-The `docker-compose.yaml` in this directory uses pre-built images from Docker Hub.
-The `grok claude` command embeds this same configuration and generates it automatically
-— you don't need this file unless you want manual control.
+Claude Code launches in different directories depending on the repo type:
 
-For manual use, set variables in `.env` or export them, then:
+| Repo type | Working directory | How detected |
+|-----------|------------------|--------------|
+| Public repo root | `/workspace/repo` | Host has `js-api/` at git root |
+| Monorepo | `/workspace/repo/public` | Host has `public/js-api/` at git root |
+| External repo | `/workspace/datagrok/packages/<folder>` | Everything else |
 
-```bash
-docker compose up -d
-```
+For **external repos**, the user's directory is bind-mounted at both `/workspace/repo`
+and `/workspace/datagrok/packages/<folder>`. Claude Code starts in the latter so it can
+walk up the directory tree to find `CLAUDE.md`, `.claude/`, and `js-api/` from the
+sparse-cloned public repo.
 
-### Building the tools-dev image
+## Sparse clone (external repos)
 
-The `Dockerfile.pkg_dev` and `entrypoint.sh` are the build recipe for the
-`datagrok/tools-dev` image published to Docker Hub. To build locally:
+When the workspace is not the public repo, the entrypoint sparse-clones it into
+`/workspace/datagrok/` using **cone mode** with `--filter=blob:none`:
 
-```bash
-cd public/tools/.devcontainer
-docker build -f Dockerfile.pkg_dev -t datagrok/tools-dev:latest .
+```
+git sparse-checkout set --cone .claude js-api libraries packages/ApiSamples
 ```
 
-## Working with repos
+This fetches only ~3 MB (vs 1.67 GB for the full repo) and completes in ~10 seconds.
+The checked-out directories provide:
+- `.claude/` — Claude Code skills and settings
+- `CLAUDE.md` — project instructions for the agent
+- `js-api/` — JS API source for reference
+- `libraries/` — shared library source
+- `packages/ApiSamples/` — runnable code examples
 
-### Public repo (default)
+### Branch resolution
 
-```bash
-cd /path/to/public
-git worktree add ~/pkg-worktrees/TASK-123 -b TASK-123
+1. `DG_PUBLIC_BRANCH` (explicit override)
+2. Current branch of the host repo (if inside the public repo)
+3. `DG_VERSION` mapped to a branch (version tags like `latest`/`bleeding-edge` → `master`)
+4. Falls back to `master`
 
-# Set WORKTREE_PATH in .env or export
-echo "WORKTREE_PATH=$HOME/pkg-worktrees/TASK-123" >> .env
-docker compose up -d
-```
+To use a private fork: `DG_PUBLIC_REPO=https://github.com/myorg/public-fork.git`
 
-Inside the container, the agent sees:
-- `/workspace/js-api/` — JS API source (read directly, no build needed for reference)
-- `/workspace/packages/ApiSamples/scripts/` — runnable code examples
-- `/workspace/help/develop/` — development guides
-- `/workspace/packages/` — all existing packages as reference
+## Entrypoint
 
-### Separate repo (e.g., private packages)
+The entrypoint (`entrypoint.sh`) runs as **root** (via `user: root` in compose) to
+handle bind-mount permission issues, then drops to the `node` user (UID 1000) via
+`setpriv` for the main process (`sleep infinity`).
 
-```bash
-git -C /path/to/my-repo worktree add ~/pkg-worktrees/TASK-123 -b TASK-123
+Steps:
+1. Fix ownership of `/workspace/datagrok` (bind-mounts create parents as root)
+2. Detect repo type (public, monorepo, or external)
+3. Sparse-clone public repo if needed (cone mode, ~10s)
+4. `chown -R node:node` on cloned files
+5. Link workspace into `packages/` (skipped if bind-mount already exists)
+6. Create symlinks at `/workspace/` for CLAUDE.md and .claude/
+7. Auto-configure `~/.grok/config.yaml` pointing to `http://datagrok:8080/api`
+8. Drop privileges: `exec setpriv --reuid=node --regid=node --init-groups "$@"`
 
-echo "WORKTREE_PATH=$HOME/pkg-worktrees/TASK-123" >> .env
-docker compose up -d
-```
+The entrypoint is **bind-mounted from the host repo** (`tools/.devcontainer/entrypoint.sh`)
+via the compose override, so changes take effect without rebuilding the Docker image.
 
-On first start, the entrypoint detects that `/workspace` is not the public repo
-(no `js-api/` at root) and automatically clones it to `/workspace/public`:
+## Compose template
 
-```
-[tools-dev] Cloning public repo (bleeding-edge) into /workspace/public...
-[tools-dev] Public repo ready at /workspace/public (branch: bleeding-edge).
-```
+The compose configuration is embedded in `bin/commands/claude.ts` — no external files
+needed. It generates three files in `$TMPDIR/dg-pkg-<project>/`:
 
-The branch is resolved in this order:
-1. `DG_PUBLIC_BRANCH` (explicit override in `.env`)
-2. `DG_VERSION` (matches the Datagrok image tag — keeps API and server in sync)
-3. Falls back to `master` if the branch/tag doesn't exist
+- `docker-compose.yaml` — main compose template
+- `.env` — resolved variables (paths, versions, ports, tokens)
+- `docker-compose.override.yaml` — host-specific volumes (entrypoint, credentials mount for external repos)
 
-Inside the container:
-- `/workspace/` — your repo
-- `/workspace/public/js-api/` — JS API source (matching Datagrok version)
-- `/workspace/public/packages/ApiSamples/scripts/` — code examples
-- `/workspace/public/help/` — docs
-- `/workspace/public/packages/` — reference packages
+### Key differences from `.devcontainer/docker-compose.yaml`
 
-To use a private fork of public, set `DG_PUBLIC_REPO` in `.env`:
-```bash
-DG_PUBLIC_REPO=https://github.com/myorg/public-fork.git
-```
+| | Embedded (grok claude) | .devcontainer/ |
+|---|---|---|
+| Version vars | Separate per service (`DATAGROK_VERSION`, `GROK_CONNECT_VERSION`, etc.) | Single `DG_VERSION` |
+| Workspace mount | `/workspace/repo` | `/workspace` |
+| grok_connect | Always on | Profile `full` only |
+| grok_pipe | `grok_pipe:latest` | `grok_pipe:${DG_VERSION}` |
+| Host ~/.grok | Not mounted (auto-created by entrypoint) | Mounted from host |
+| Entrypoint | Bind-mounted from repo via override | Baked into image |
+| User | `root` (drops to `node` via setpriv) | `node` (from Dockerfile) |
 
-Worktrees keep full git connectivity — commit, push, fetch, PR all work.
+## Credential handling
+
+Claude Code credentials are **copied** into the container after startup (not
+bind-mounted) to avoid permission issues — host files may have different UID/GID
+than the container's `node` user.
+
+Files copied from `~/.claude/`:
+- `.credentials.json` — OAuth credentials
+- `settings.json` — Claude Code settings
+- `settings.local.json` — local settings
+
+After copying, ownership is fixed: `chown -R node:node /home/node/.claude`
+
+The host `~/.claude` directory is found by searching (in order):
+1. `CLAUDE_HOME` environment variable
+2. `$HOME/.claude`
+3. `$USERPROFILE/.claude` (Windows)
+4. `$APPDATA/../.claude` (Windows fallback)
+
+## Profiles
+
+| Profile | Services added | Use case |
+|---------|---------------|----------|
+| (none) | postgres, rabbitmq, grok_pipe, datagrok, grok_connect, tools-dev | Basic package dev |
+| `scripting` | + jupyter_kernel_gateway | Python/R/Julia scripts |
+| `demo` | + world, test_db, northwind | Demo databases |
+| `full` | + grok_spawner, JKG, demo DBs | Everything |
+
+## tools-dev container
+
+Based on `node:22-bookworm-slim`. Pre-installed:
+- Google Chrome stable (for Puppeteer)
+- Playwright + Chromium
+- `datagrok-tools` (grok CLI) — global npm
+- `@anthropic-ai/claude-code` — global npm
+- git, curl, jq, docker CLI
+- Node.js 22
+
+Runs as **root** in compose (entrypoint drops to `node` user for the main process).
 
 ## MCP plugins: Jira and GitHub
 
@@ -176,100 +213,42 @@ claude mcp add mcp-atlassian -s user -- \
   --jira-token "$JIRA_TOKEN"
 ```
 
-The agent can then:
-- Search for issues: "find similar bugs to GROK-12345"
-- Read issue details, comments, attachments
-- Update issue status, add comments
-- Create new issues
-
 ### GitHub
 
 ```bash
-# Inside tools-dev, register the MCP server:
 claude mcp add github -s user -- \
   npx -y @modelcontextprotocol/server-github
 ```
 
-Requires `GITHUB_TOKEN` in the environment (already passed from `.env`). The agent can:
-- Search issues and PRs across repos
-- Read issue comments and PR diffs
-- Create issues, PRs, and comments
-- Check CI status
-
-### Interactive token setup
-
-If tokens are not pre-configured, the agent asks the user:
-
-```
-Agent: I need a Jira API token to search for similar issues.
-       Go to https://id.atlassian.com/manage-profile/security/api-tokens
-       and create a token. Paste it here.
-User:  <pastes token>
-Agent: <configures MCP server and proceeds>
-```
-
-The same flow works for GitHub tokens and grok dev keys.
+Requires `GITHUB_TOKEN` in the environment (already passed from `.env`).
 
 ## Testing
 
-### Playwright (browser automation)
-
-Playwright is pre-installed with Chromium. Use it for custom browser automation,
-E2E tests, and UI interaction scenarios.
+### grok test (Puppeteer-based)
 
 ```bash
-# Inside tools-dev:
-cd /workspace/packages/MyPkg
-
-# Run Playwright tests (if the package has them)
-npx playwright test --project chromium
-
-# Or write ad-hoc automation
-npx playwright codegen http://datagrok:8080
-```
-
-### grok test (Puppeteer-based package tests)
-
-Standard Datagrok package testing via the `grok` CLI:
-
-```bash
-# Inside tools-dev:
-cd /workspace/packages/MyPkg
+cd /workspace/datagrok/packages/MyPkg
 grok test --host local              # headless
 grok test --host local --gui        # visible browser
 grok test --host local --verbose    # detailed output
-grok test --host local --category "MyCategory"  # filter tests
 ```
 
-### Chrome remote debugging
-
-`grok test --gui` runs Chrome with `--remote-debugging-port=9222`. Port 9222 is
-exposed to the host.
-
-On host: open `chrome://inspect` → Configure → add `localhost:9222` → click "inspect"
-on the test session. Set breakpoints in package source during test execution.
-
-### Developing test scenarios
-
-The agent can:
-1. Read existing tests in `packages/ApiTests/` and other packages for patterns
-2. Create new test files following the `package-test.ts` template
-3. Run tests and analyze failures
-4. Generate test cases from Jira issue descriptions or GitHub issues
+### Playwright
 
 ```bash
-# Scaffold a test file in a package
-cd /workspace/packages/MyPkg
-grok add test
+cd /workspace/datagrok/packages/MyPkg
+npx playwright test --project chromium
 ```
 
-## Publishing packages
+### Chrome remote debugging
 
-### To the local Datagrok instance
+`grok test --gui` runs Chrome with `--remote-debugging-port=9222`.
+On host: `chrome://inspect` → Configure → add `localhost:9222`
+
+## Publishing packages
 
 ```bash
-# Inside tools-dev:
-cd /workspace/packages/MyPkg
+cd /workspace/datagrok/packages/MyPkg
 grok publish                    # debug mode (visible only to dev)
 grok publish --release          # public release
 grok publish --build            # build webpack first
@@ -278,184 +257,17 @@ grok publish --build            # build webpack first
 ### To an external server
 
 ```bash
-# Add a server config
 grok config add --alias prod \
   --server https://example.datagrok.ai/api \
   --key <dev-key>
-
-# Publish to it
 grok publish prod --release --build
 ```
 
-The agent handles the full cycle: build, check, publish, verify in the UI.
-
-## Managing the Datagrok stand
-
-The tools-dev container has the Docker socket mounted, so the agent can manage the
-entire compose stack from inside.
-
-### Version switching
-
-```bash
-# Inside tools-dev (or from host):
-DG_VERSION=1.22.0 docker compose up -d --pull always
-```
-
-When the workspace is a separate repo (not public), the auto-cloned public repo
-should also be updated to match the new version:
-
-```bash
-# Inside tools-dev — update the public clone to match new DG_VERSION:
-cd /workspace/public && git fetch && git checkout 1.22.0
-```
-
-The agent does this autonomously when asked:
-```
-User:  Switch to Datagrok 1.22.0
-Agent: <updates DG_VERSION, pulls new images, updates public branch>
-       Datagrok 1.22.0 is running. Public repo updated to 1.22.0.
-```
-
-### DB reset / redeploy
-
-```bash
-docker compose down -v && docker compose up -d
-```
-
-### Adding profiles on the fly
-
-```bash
-# Need demo databases now
-docker compose --profile demo up -d
-
-# Need everything
-docker compose --profile full up -d
-```
-
-## Profiles
-
-| Profile | Services added | Use case |
-|---------|---------------|----------|
-| (none) | postgres, rabbitmq, grok_pipe, datagrok, tools-dev | Basic package dev |
-| `demo` | + world, test_db, northwind | Need demo databases |
-| `scripting` | + jupyter_kernel_gateway | Need Python/R/Julia scripts |
-| `full` | + grok_connect, grok_spawner, demo DBs, JKG | Everything |
-
-## JS API and code reference
-
-The agent reads JS API source and documentation directly from the workspace — no
-generated docs needed.
-
-### Key paths (public repo at `/workspace`)
-
-| What | Path |
-|------|------|
-| JS API source (types, classes, methods) | `js-api/src/` |
-| JS API entry points (grok, ui, dg) | `js-api/grok.ts`, `js-api/ui.ts`, `js-api/dg.ts` |
-| JS API CLAUDE.md (module map, patterns) | `js-api/CLAUDE.md` |
-| Runnable code samples | `packages/ApiSamples/scripts/` |
-| Package development guide | `help/develop/packages/` |
-| All platform help docs | `help/` |
-| Existing packages (patterns) | `packages/` |
-| CLI tool source | `tools/` |
-
-### Key paths (separate repo — public auto-cloned)
-
-Same as above, prefixed with `public/`:
-- `public/js-api/src/`, `public/packages/ApiSamples/scripts/`, etc.
-
-The public branch matches `DG_VERSION` by default, so js-api types stay in sync
-with the running Datagrok server.
-
-### CLAUDE.md for the agent
-
-Add to your project's CLAUDE.md so the agent knows where to look:
-
-```markdown
-## Reference
-
-- JS API: read source in `js-api/src/` — see `js-api/CLAUDE.md` for module map
-- Code samples: `packages/ApiSamples/scripts/` — runnable examples for eval
-- Help docs: `help/develop/` — guides for packages, viewers, functions
-- Existing packages: `packages/` — real-world patterns
-```
-
 ## Exposing the client
 
-- Datagrok UI: `http://localhost:${DG_PORT:-8080}`
-- Default credentials: **admin / admin** (created on first deploy)
-
-### grok CLI config inside the container
-
-The entrypoint auto-creates `~/.grok/config.yaml` with the local Datagrok instance
-(dev key `admin`). The grok CLI is ready to use immediately — no manual config needed.
-
-If you need to reconfigure:
-
-```bash
-# Inside tools-dev:
-grok config add --alias local \
-  --server http://datagrok:8080/api \
-  --key admin --default
-```
-
-## Claude Code inside the container
-
-Mount `~/.claude/` from host (already in the compose file) for credentials and
-config. Pass `ANTHROPIC_API_KEY` via `.env` or shell export.
-
-```bash
-# Single entry point — launch Claude Code interactively
-docker exec -it <tools-dev_container> claude --dangerously-skip-permissions
-
-# One-shot command
-docker exec <tools-dev_container> claude -p "publish the Chem package" \
-  --dangerously-skip-permissions
-```
-
-The agent can:
-- Build, test, and publish packages
-- Search Jira/GitHub for context (via MCP plugins)
-- Manage the Datagrok stand (version switch, redeploy, DB reset)
-- Ask the user for tokens and auth when needed
-- Read js-api source and ApiSamples for reference
-
-## Quick reference
-
-```bash
-# Start (basic)
-docker compose up -d
-
-# Start (everything)
-docker compose --profile full up -d
-
-# Launch Claude agent (single entry point)
-docker exec -it <tools-dev> claude --dangerously-skip-permissions
-
-# Shell into tools-dev
-docker exec -it <tools-dev> bash
-
-# Publish a package
-docker exec <tools-dev> bash -c "cd /workspace/packages/MyPkg && grok publish"
-
-# Run grok tests
-docker exec <tools-dev> bash -c "cd /workspace/packages/MyPkg && grok test --host local"
-
-# Run Playwright tests
-docker exec <tools-dev> bash -c "cd /workspace/packages/MyPkg && npx playwright test"
-
-# Version switch
-DG_VERSION=1.22.0 docker compose up -d --pull always
-
-# DB reset
-docker compose down -v && docker compose up -d
-
-# Logs
-docker compose logs -f datagrok
-
-# Stop
-docker compose down
-```
+- Datagrok UI: `http://localhost:${DG_PORT}` (port shown at startup, or use `--port` to fix it)
+- Default credentials: **admin / admin**
+- grok CLI inside container: auto-configured to `http://datagrok:8080/api` with key `admin`
 
 ## Troubleshooting
 
@@ -463,39 +275,21 @@ docker compose down
 ```bash
 docker compose logs datagrok
 # Wait for DB migrations — first start takes 1-2 minutes
-# Look for: "Server started on port 8080"
 ```
 
 ### grok publish fails
-Ensure `~/.grok/config.yaml` inside the container points to `http://datagrok:8080/api`
-with a valid dev key. The container reaches Datagrok via Docker DNS, not `localhost`.
-
-### Chrome / Playwright not working
-```bash
-docker exec <tools-dev> google-chrome-stable --version
-docker exec <tools-dev> npx playwright --version
-```
-If missing, pull the latest image: `docker pull datagrok/tools-dev:latest`
+Ensure `~/.grok/config.yaml` inside the container points to `http://datagrok:8080/api`.
+The container reaches Datagrok via Docker DNS (`datagrok`), not `localhost`.
 
-### MCP plugins not connecting
-```bash
-# Verify env vars are set
-docker exec <tools-dev> env | grep -E 'JIRA|GITHUB'
-# Re-register if needed
-docker exec -it <tools-dev> claude mcp add mcp-atlassian -s user -- \
-  npx -y mcp-atlassian --jira-url "$JIRA_URL" \
-  --jira-username "$JIRA_USERNAME" --jira-token "$JIRA_TOKEN"
-```
+### Permission denied on /workspace/datagrok
+The entrypoint runs as root and fixes ownership. If using the image directly (not via
+`grok claude`), add `user: root` to the compose service definition.
 
-### Agent can't manage Docker (version switch, redeploy)
-The Docker socket must be mounted and the `dev` user must be in the `docker` group:
-```bash
-docker exec <tools-dev> docker ps
-```
-If permission denied, check that `/var/run/docker.sock` is mounted and accessible.
+### Agent can't manage Docker
+The Docker socket must be mounted. Check: `docker exec <tools-dev> docker ps`
 
 ### Container can't resolve `datagrok` hostname
 All services must be on the same Docker network:
 ```bash
-docker network inspect dg-pkg-${TASK_KEY:-default}-net
+docker network inspect dg-pkg-<project>-net
 ```

package/.devcontainer/entrypoint.sh

@@ -13,6 +13,11 @@ resolve_branch() {
 }
 
 PUBLIC_DIR="${DG_PUBLIC_DIR:-/workspace/datagrok}"
+# Ensure workspace dirs are writable by node user (bind-mounts create parents as root)
+chown node:node /workspace "$PUBLIC_DIR" 2>/dev/null || true
+# Allow git to operate on dirs owned by different users (root runs git, dir owned by node)
+git config --global --add safe.directory "$PUBLIC_DIR" 2>/dev/null || true
+git config --global init.defaultBranch master 2>/dev/null || true
 # Detect if /workspace/repo IS the public repo.
 # Require .git to avoid false positives from packages that have public/js-api via npm link.
 if [ -e "/workspace/repo/.git" ] && [ -d "/workspace/repo/js-api" ]; then
@@ -29,31 +34,40 @@ else
   else
     BRANCH=$(resolve_branch "${DG_VERSION:-latest}")
   fi
-  # Sparse checkout: only fetch dirs needed for package context (js-api, libraries, packages)
-  # plus root files (CLAUDE.md, .claude/, etc.). Uses --depth 1 without blob filter so all
-  # blobs arrive in one pack — avoids slow on-demand fetching during checkout.
+  # Sparse checkout (cone mode) with partial clone: only fetch js-api, libraries, and
+  # ApiSamples. Cone mode integrates with --filter=blob:none so the server only sends
+  # blobs for the included directories (~3 MB vs 1.67 GB for the full tree).
   sparse_clone() {
     local branch="$1"
     # Use init+fetch instead of clone to handle pre-existing directories (e.g. mount points)
-    git init "$PUBLIC_DIR" \
-      && git -C "$PUBLIC_DIR" remote add origin "$REPO" \
-      && git -C "$PUBLIC_DIR" sparse-checkout set --no-cone \
-           '/*' '!connectors/' '!docker/' '!docusaurus/' '!docusaurus-static/' \
-           '!environments/' '!hooks/' '!misc/' 'python-api/' '!datagrok-celery-task/' \
-           '/js-api/**' '/libraries/**' '/packages/**' \
-      && git -C "$PUBLIC_DIR" fetch --depth 1 origin "$branch" \
-      && git -C "$PUBLIC_DIR" checkout -B "$branch" FETCH_HEAD
+    git init -q "$PUBLIC_DIR" \
+      && (git -C "$PUBLIC_DIR" remote add origin "$REPO" 2>/dev/null || git -C "$PUBLIC_DIR" remote set-url origin "$REPO") \
+      && git -C "$PUBLIC_DIR" config remote.origin.promisor true \
+      && git -C "$PUBLIC_DIR" config remote.origin.partialclonefilter blob:none \
+      && git -C "$PUBLIC_DIR" sparse-checkout set --cone .claude js-api libraries packages/ApiSamples \
+      && git -C "$PUBLIC_DIR" fetch -q --depth 1 --filter=blob:none origin "$branch" \
+      && git -C "$PUBLIC_DIR" checkout -q -B "$branch" FETCH_HEAD
   }
-  # Clear directory contents without removing the dir itself (may be a mount point)
-  clear_dir() {
-    find "$1" -mindepth 1 -delete 2>/dev/null || rm -rf "$1"/* "$1"/.[!.]* 2>/dev/null || true
+  # Clear git state without touching bind-mounted subdirs (e.g. packages/awesome)
+  clear_git() {
+    rm -rf "$1/.git" 2>/dev/null || true
   }
   echo "[tools-dev] Cloning public repo ($BRANCH, sparse) into $PUBLIC_DIR..."
-  sparse_clone "$BRANCH" \
-    || { echo "[tools-dev] Branch '$BRANCH' clone failed, falling back to master."
-         clear_dir "$PUBLIC_DIR"
-         sparse_clone "master"; }
-  echo "[tools-dev] Public repo ready at $PUBLIC_DIR (branch: $(git -C "$PUBLIC_DIR" branch --show-current))."
+  if sparse_clone "$BRANCH"; then
+    echo "[tools-dev] Public repo ready."
+  elif [ "$BRANCH" != "master" ]; then
+    echo "[tools-dev] Branch '$BRANCH' clone failed, falling back to master."
+    clear_git "$PUBLIC_DIR"
+    if sparse_clone "master"; then
+      echo "[tools-dev] Public repo ready (branch: master)."
+    else
+      echo "[tools-dev] WARNING: Failed to clone public repo."
+    fi
+  else
+    echo "[tools-dev] WARNING: Failed to clone public repo."
+  fi
+  # Ensure node user can read cloned files (entrypoint runs as root)
+  chown -R node:node "$PUBLIC_DIR" 2>/dev/null || true
 fi
 
 # ── Mount workspace inside public repo for non-public workspaces ──
@@ -64,21 +78,20 @@ if [ -e "/workspace/repo/.git" ] && [ -d "/workspace/repo/js-api" ]; then
 elif [ -e "/workspace/repo/.git" ] && [ -d "/workspace/repo/public/js-api" ]; then
   echo "[tools-dev] Monorepo detected — public context at /workspace/repo/public/."
 elif [ -d "$PUBLIC_DIR/js-api" ]; then
-  # Cloned public repo — link workspace into packages/ and expose context at /workspace/
   LINK_NAME="${FOLDER_NAME:-$TASK_KEY}"
   if [ -n "$LINK_NAME" ]; then
     mkdir -p "$PUBLIC_DIR/packages" 2>/dev/null || true
-    [ ! -e "$PUBLIC_DIR/packages/$LINK_NAME" ] && ln -s /workspace/repo "$PUBLIC_DIR/packages/$LINK_NAME"
-    echo "[tools-dev] Workspace linked at $PUBLIC_DIR/packages/$LINK_NAME"
+    if [ ! -d "$PUBLIC_DIR/packages/$LINK_NAME" ]; then
+      ln -sfn /workspace/repo "$PUBLIC_DIR/packages/$LINK_NAME"
+    fi
+    echo "[tools-dev] Workspace at $PUBLIC_DIR/packages/$LINK_NAME"
   fi
   PUBLIC_BASENAME=$(basename "$PUBLIC_DIR")
-  [ ! -e /workspace/.claude ] && ln -s "$PUBLIC_BASENAME/.claude" /workspace/.claude
-  [ ! -e /workspace/CLAUDE.md ] && ln -s "$PUBLIC_BASENAME/CLAUDE.md" /workspace/CLAUDE.md
-  echo "[tools-dev] Linked public repo context at /workspace/"
+  ln -sfn "$PUBLIC_BASENAME/.claude" /workspace/.claude 2>/dev/null || true
+  ln -sfn "$PUBLIC_BASENAME/CLAUDE.md" /workspace/CLAUDE.md 2>/dev/null || true
 fi
 
 # Auto-configure grok CLI to point to the local Datagrok instance.
-# Only creates the config if it doesn't already exist (preserves host config).
 GROK_DIR="/home/node/.grok"
 GROK_CFG="$GROK_DIR/config.yaml"
 if [ ! -f "$GROK_CFG" ] || [ ! -s "$GROK_CFG" ]; then
@@ -91,9 +104,10 @@ servers:
     key: admin
 YAML
   [ -s "$GROK_CFG" ] && echo "[tools-dev] Created grok config at $GROK_CFG"
-elif ! grep -q "datagrok:8080" "$GROK_CFG" 2>/dev/null; then
-  echo "[tools-dev] Note: existing grok config found. Add 'local' server with:"
-  echo "  grok config add --alias local --server http://datagrok:8080/api --key admin --default"
 fi
 
+# Drop to node user for the main process (entrypoint runs as root for permission fixes)
+if [ "$(id -u)" = "0" ]; then
+  exec setpriv --reuid=node --regid=node --init-groups "$@"
+fi
 exec "$@"

package/bin/commands/claude.js

@@ -259,6 +259,7 @@ services:
     networks:
       dg:
         aliases: [tools-dev]
+    user: root
     stdin_open: true
     tty: true
     restart: unless-stopped
@@ -321,7 +322,7 @@ function findFreePort() {
     srv.on('error', reject);
   });
 }
-function writeProjectFiles(taskKey, args, worktreeRoot, dgPort) {
+function writeProjectFiles(taskKey, args, worktreeRoot, dgPort, repoRoot) {
   const projectDir = getProjectDir(taskKey);
   if (!_fs.default.existsSync(projectDir)) _fs.default.mkdirSync(projectDir, {
     recursive: true
@@ -349,14 +350,19 @@ function writeProjectFiles(taskKey, args, worktreeRoot, dgPort) {
   // Bind-mount local entrypoint so fixes take effect without rebuilding the image
   if (hasLocalEntrypoint) volumes.push(`      - "${toDockerPath(entrypointPath)}:/usr/local/bin/entrypoint.sh"`);
 
-  // Claude profile (~/.claude + ~/.claude.json)
+  // For external repos, also mount workspace inside the public repo tree so Claude Code
+  // sees the real path (not a symlink that resolves back to /workspace/repo).
+  const isPublic = repoRoot ? isPublicRepo(repoRoot) : false;
+  if (!isPublic) {
+    const folderName = _path.default.basename(worktreeRoot);
+    volumes.push(`      - "${toDockerPath(worktreeRoot)}:/workspace/datagrok/packages/${folderName}"`);
+  }
+
+  // Claude profile: credentials are copied into the container after startup (not bind-mounted)
+  // to avoid permission issues — host files may have different UID/GID than the container's
+  // node user.
   const claudeHome = findClaudeHome();
-  if (claudeHome) {
-    volumes.push(`      - "${toDockerPath(claudeHome)}:/home/node/.claude"`);
-    const claudeState = _path.default.join(_path.default.dirname(claudeHome), '.claude.json');
-    if (_fs.default.existsSync(claudeState) && _fs.default.statSync(claudeState).isFile()) volumes.push(`      - "${toDockerPath(claudeState)}:/home/node/.claude.json"`);
-    color.info(`Claude profile: ${claudeHome}`);
-  } else color.warn('No Claude profile found. Set CLAUDE_HOME or run "claude" locally to log in.');
+  if (claudeHome) color.info(`Claude profile: ${claudeHome}`);else color.warn('No Claude profile found. Set CLAUDE_HOME or run "claude" locally to log in.');
   const overridePath = _path.default.join(projectDir, 'docker-compose.override.yaml');
   if (volumes.length > 0) {
     const override = ['services:', '  tools-dev:', '    volumes:', ...volumes].join('\n') + '\n';
@@ -539,7 +545,7 @@ async function claude(args) {
   color.info(`Datagrok UI will be at: http://localhost:${dgPort}`);
 
   // Write compose + .env to temp dir (no external file dependencies)
-  const projectDir = writeProjectFiles(taskKey, args, worktreeRoot, dgPort);
+  const projectDir = writeProjectFiles(taskKey, args, worktreeRoot, dgPort, repoRoot);
   color.info(`Workspace: ${worktreeRoot}`);
 
   // Start containers
@@ -549,11 +555,25 @@ async function claude(args) {
     color.error('Failed to start containers.');
     return false;
   }
+  const containerName = `dg-pkg-${taskKey.toLowerCase()}-tools-dev-1`;
+
+  // Copy Claude credentials into the container (avoids bind-mount permission issues)
+  const claudeHomePath = findClaudeHome();
+  if (claudeHomePath) {
+    const claudeFiles = ['.credentials.json', 'settings.json', 'settings.local.json'];
+    for (const file of claudeFiles) {
+      const filePath = _path.default.join(claudeHomePath, file);
+      if (_fs.default.existsSync(filePath) && _fs.default.statSync(filePath).isFile()) (0, _child_process.spawnSync)('docker', ['cp', filePath, `${containerName}:/home/node/.claude/${file}`]);
+    }
+    const claudeState = _path.default.join(_path.default.dirname(claudeHomePath), '.claude.json');
+    if (_fs.default.existsSync(claudeState) && _fs.default.statSync(claudeState).isFile()) (0, _child_process.spawnSync)('docker', ['cp', claudeState, `${containerName}:/home/node/.claude.json`]);
+    // Fix ownership — docker cp creates files as root
+    (0, _child_process.spawnSync)('docker', ['exec', '-u', 'root', containerName, 'chown', '-R', 'node:node', '/home/node/.claude']);
+  }
 
   // Determine Claude working directory based on repo type
   // Only trust public-repo markers when we are inside a real git repo — packages can have
   // public/js-api via node_modules symlinks, which would cause a false positive.
-  const containerName = `dg-pkg-${taskKey.toLowerCase()}-tools-dev-1`;
   let claudeWorkDir;
   if (repoRoot && _fs.default.existsSync(_path.default.join(repoRoot, 'js-api'))) claudeWorkDir = '/workspace/repo';else if (repoRoot && _fs.default.existsSync(_path.default.join(repoRoot, 'public', 'js-api'))) claudeWorkDir = '/workspace/repo/public';else {
     // External repo: entrypoint clones public repo and creates symlink — wait for it
@@ -587,7 +607,7 @@ async function claude(args) {
   const claudeArgs = ['--dangerously-skip-permissions'];
   if (args.prompt) claudeArgs.push('-p', args.prompt);
   color.info(`Launching Claude Code in container ${containerName}...`);
-  (0, _child_process.spawnSync)('docker', ['exec', '-it', '-w', claudeWorkDir, containerName, 'claude', ...claudeArgs], {
+  (0, _child_process.spawnSync)('docker', ['exec', '-it', '-u', 'node', '-w', claudeWorkDir, containerName, 'claude', ...claudeArgs], {
     stdio: 'inherit'
   });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "datagrok-tools",
-  "version": "6.0.6",
+  "version": "6.0.8",
   "description": "Utility to upload and publish packages to Datagrok",
   "homepage": "https://github.com/datagrok-ai/public/tree/master/tools#readme",
   "dependencies": {