feat(projects): add project from a Git URL (#94)

CLAUDE.md

@@ -20,7 +20,7 @@ docker compose up -d
 docker compose logs -f claude-chat
 ```
 
-No linting and no build step configured. `npm test` chains 79 test files under `test/`: 19 DOM-less render/UI-logic tests (`test/render/*.test.mjs`, run through `node --test`) plus 60 plain-`node` suites in `test/` covering the overload detector, env load order, multi-agent results, terminals, bots, telegram, updates, kanban scheduling, the Kanban card's run-settings badges (`kanban-run-badges.test.js` pins the card's model/effort/engine chain against the one `startTask` actually resolves — the two live in different files and the card silently lies when they drift), the board-only `create_task` status (`task-backlog.test.js`), i18n completeness, the config precedence resolver plus its secret masking, usage-limit detection, authentication-failure classification (`auth-errors.test.js`, which pins that the detector runs BEFORE the auto-continue in all three agent loops — a reorder there silently restores #86), the filesystem path guard (including the SVG sandbox header and the symlink rule on the `@`-mention search endpoints) plus the tunnel-blocks-terminal rule, WS session re-subscription, the SSH remote CLI-session import, the live engine pane / interactive-prompt watchdog, the subscription engine's spawn command (`engine-spawn-cmd.test.js` starts a real tmux session with a 40 KB system prompt and asserts the child's argv byte-identical — the tmux command may never carry the prompt inline, see #96), the cross-project global workspace aggregation, the rule that an SSH credential never leaves the server process, the Windows command-quoting oracle, the auth token lifecycle, the multi-agent dependency scheduler (waves, plan sanitising, and the rule that a failure warning must survive dep-context truncation), the SSH stream parser's three guards, the SSH run's termination guarantee (`ssh-termination.test.js` drives `ClaudeSSH.send()` through a fake ssh2 `Client` in `require.cache` and asserts `onDone` fires EXACTLY once on every ending — a missed one hangs the chat forever, a doubled one re-emits stderr) and the recovery contract of "Restart Session" (`session-restart.test.js` boots a real server against a fake `claude` that never exits, then pins that a restart ABORTS that turn and releases the session instead of refusing), the remote non-interactive shell environment (`remote-env.test.js`, which runs the generated prelude through real `bash -lc`: it must parse, print nothing on stdout, and never end on a false test — the caller chains `&& claude …` behind it), the remote CLI-list framing parser, the bot inbox's SQL seam (`bot-inbox.test.js` pins that `from_bot AS "from"` keeps the exact key `planInboxDelivery` reads — rename one without the other and every letter is silently retired as malformed), the one-time config/.env migration onto CCS_CONFIG_PATH and the mid-task clarification delivery contract on the subscription engine (`interrupt-delivery.test.js` — pins that the tmux injection block sits BEFORE the poll loop's completion `break`, that draining does not imply delivery, that a failed paste is re-queued and warns non-terminally, and that the task runner passes the same callbacks the chat path does), the CLAUDE.md / AGENTS.md discovery rules (`agents-md.test.js`, which also pins that AGENTS.md reaches the subprocess as `--append-system-prompt` and never as `--system-prompt`), and the remote file browser's three guard layers (`remote-files.test.js` runs the generated POSIX script through a real `/bin/sh` against a temp tree that contains symlinks OUT of the project; `remote-files-api.test.js` boots a server against a fake remote via `CCS_REMOTE_EXEC_HOOK` and drives `/api/files` the way the SPA does), the editor deep links (`editor-links.test.js` pins the two URI shapes literally — the browser link puts `vscode-remote` in the AUTHORITY and the CLI argument puts it in the SCHEME, and collapsing the two silently breaks one path; `editor-open-api.test.js` boots a real server with `PATH` pointed at an EMPTY directory, which both makes the `opened:'client'` fallback deterministic and guarantees the suite never launches an editor window on a developer's desktop), and the new-chat defaults chain (`chat-defaults.test.js` pins the pure resolver — the built-ins are asserted to be exactly what the SPA hardcoded before #58, and the choice lists to be exactly the toolbar's `data-v` sets and `MODEL_MAP`'s aliases; `chat-defaults-api.test.js` boots a real server in a throwaway `APP_DIR` and pins that a project writes back a SPARSE override object — a five-key snapshot passes every other assertion in that file and still breaks the feature). On the render side, `tables.test.mjs` also pins the ReDoS bound in renderMd step 3.4, `xss.test.mjs` runs 24 adversarial payloads end-to-end, and `forged-tokens.test.mjs` covers the case where user text contains the renderer's own placeholder control bytes, and `pane-font.test.mjs` pins the clamp DIRECTION of `_fitEnginePaneFont` (a wide engine pane may only shrink; a narrow split pane must be allowed to grow). `script-scope.test.mjs` pins which `<script>` block a helper is declared in — declarations hoist only within their own block, so a helper used by `loadSess()` must not live in the terminal block at the bottom of the file. Note the glob: a file under `test/render/` whose name does not end in `.test.mjs` is NEVER run — `_load.selftest.mjs` sat there unexecuted until it was renamed to `loader.test.mjs`. It runs serially and aborts on the first failing file. `.github/workflows/ci.yml` runs it on every push and PR to `main` (tmux installed, so the five tmux-dependent suites do not self-skip).
+No linting and no build step configured. `npm test` chains 80 test files under `test/`: 19 DOM-less render/UI-logic tests (`test/render/*.test.mjs`, run through `node --test`) plus 61 plain-`node` suites in `test/` covering the overload detector, env load order, multi-agent results, terminals, bots, telegram, updates, kanban scheduling, the Kanban card's run-settings badges (`kanban-run-badges.test.js` pins the card's model/effort/engine chain against the one `startTask` actually resolves — the two live in different files and the card silently lies when they drift), the board-only `create_task` status (`task-backlog.test.js`), i18n completeness, the config precedence resolver plus its secret masking, usage-limit detection, authentication-failure classification (`auth-errors.test.js`, which pins that the detector runs BEFORE the auto-continue in all three agent loops — a reorder there silently restores #86), the filesystem path guard (including the SVG sandbox header and the symlink rule on the `@`-mention search endpoints) plus the tunnel-blocks-terminal rule, WS session re-subscription, the SSH remote CLI-session import, the live engine pane / interactive-prompt watchdog, the subscription engine's spawn command (`engine-spawn-cmd.test.js` starts a real tmux session with a 40 KB system prompt and asserts the child's argv byte-identical — the tmux command may never carry the prompt inline, see #96), the cross-project global workspace aggregation, the add-project-from-Git-URL endpoint (`git-clone.test.js` boots a server whose `PATH` holds a fake `git` and pins the transport allowlist, the `--` argv shape and the failure cleanup — see #94), the rule that an SSH credential never leaves the server process, the Windows command-quoting oracle, the auth token lifecycle, the multi-agent dependency scheduler (waves, plan sanitising, and the rule that a failure warning must survive dep-context truncation), the SSH stream parser's three guards, the SSH run's termination guarantee (`ssh-termination.test.js` drives `ClaudeSSH.send()` through a fake ssh2 `Client` in `require.cache` and asserts `onDone` fires EXACTLY once on every ending — a missed one hangs the chat forever, a doubled one re-emits stderr) and the recovery contract of "Restart Session" (`session-restart.test.js` boots a real server against a fake `claude` that never exits, then pins that a restart ABORTS that turn and releases the session instead of refusing), the remote non-interactive shell environment (`remote-env.test.js`, which runs the generated prelude through real `bash -lc`: it must parse, print nothing on stdout, and never end on a false test — the caller chains `&& claude …` behind it), the remote CLI-list framing parser, the bot inbox's SQL seam (`bot-inbox.test.js` pins that `from_bot AS "from"` keeps the exact key `planInboxDelivery` reads — rename one without the other and every letter is silently retired as malformed), the one-time config/.env migration onto CCS_CONFIG_PATH and the mid-task clarification delivery contract on the subscription engine (`interrupt-delivery.test.js` — pins that the tmux injection block sits BEFORE the poll loop's completion `break`, that draining does not imply delivery, that a failed paste is re-queued and warns non-terminally, and that the task runner passes the same callbacks the chat path does), the CLAUDE.md / AGENTS.md discovery rules (`agents-md.test.js`, which also pins that AGENTS.md reaches the subprocess as `--append-system-prompt` and never as `--system-prompt`), and the remote file browser's three guard layers (`remote-files.test.js` runs the generated POSIX script through a real `/bin/sh` against a temp tree that contains symlinks OUT of the project; `remote-files-api.test.js` boots a server against a fake remote via `CCS_REMOTE_EXEC_HOOK` and drives `/api/files` the way the SPA does), the editor deep links (`editor-links.test.js` pins the two URI shapes literally — the browser link puts `vscode-remote` in the AUTHORITY and the CLI argument puts it in the SCHEME, and collapsing the two silently breaks one path; `editor-open-api.test.js` boots a real server with `PATH` pointed at an EMPTY directory, which both makes the `opened:'client'` fallback deterministic and guarantees the suite never launches an editor window on a developer's desktop), and the new-chat defaults chain (`chat-defaults.test.js` pins the pure resolver — the built-ins are asserted to be exactly what the SPA hardcoded before #58, and the choice lists to be exactly the toolbar's `data-v` sets and `MODEL_MAP`'s aliases; `chat-defaults-api.test.js` boots a real server in a throwaway `APP_DIR` and pins that a project writes back a SPARSE override object — a five-key snapshot passes every other assertion in that file and still breaks the feature). On the render side, `tables.test.mjs` also pins the ReDoS bound in renderMd step 3.4, `xss.test.mjs` runs 24 adversarial payloads end-to-end, and `forged-tokens.test.mjs` covers the case where user text contains the renderer's own placeholder control bytes, and `pane-font.test.mjs` pins the clamp DIRECTION of `_fitEnginePaneFont` (a wide engine pane may only shrink; a narrow split pane must be allowed to grow). `script-scope.test.mjs` pins which `<script>` block a helper is declared in — declarations hoist only within their own block, so a helper used by `loadSess()` must not live in the terminal block at the bottom of the file. Note the glob: a file under `test/render/` whose name does not end in `.test.mjs` is NEVER run — `_load.selftest.mjs` sat there unexecuted until it was renamed to `loader.test.mjs`. It runs serially and aborts on the first failing file. `.github/workflows/ci.yml` runs it on every push and PR to `main` (tmux installed, so the five tmux-dependent suites do not self-skip).
 
 ## Architecture
 
@@ -635,6 +635,32 @@ the session's inside the runner. `kbRunBadges()` in `public/kanban.html` replace
   no turn budget, no retry and no session resume. Wiring one into `taskWorker` is a new
   execution backend, not a dropdown.
 
+### Add project from a Git URL (issue #94)
+
+`POST /api/projects/clone` runs `git clone <url>` into `<parentDir>/<repo>` and
+registers the result through the same `registerLocalProject()` the plain create uses.
+The SPA exposes it as one extra row in the New-project modal: the folder the user
+browsed to is the PARENT, and a non-empty URL turns "Add project" into a clone.
+`git-clone.js` holds the pure half; `test/git-clone.test.js` drives the endpoint
+against a real server whose `PATH` holds a fake `git`.
+
+- **Transports are an allowlist, enforced twice.** `parseCloneUrl()` accepts
+  `http(s)://`, `ssh://`, `git://` and `user@host:path` — `ext::` executes an arbitrary
+  command and `file://` / a bare path clone anything this process can read. The same
+  list rides as `GIT_ALLOW_PROTOCOL` so a redirect or submodule cannot widen it.
+- **Nothing user-supplied may look like an option.** URL and target follow `--`;
+  `--branch <b>` cannot, so a branch starting with `-` is refused before git sees it.
+  The directory name is one path segment (`DIR_NAME_RE`), joined onto a parent that
+  passed `isPathAllowed()` — a registered workdir widens that allowlist, which is why
+  the gate cannot be skipped here any more than in `POST /api/projects`.
+- **It must fail, not wait.** stdin is closed, `GIT_TERMINAL_PROMPT=0`, no TTY: a
+  credential or host-key question fails at once (measured: a private/nonexistent GitHub
+  URL answers in ~0.4 s with git's own line). `CCS_GIT_CLONE_TIMEOUT_MS` (10 min) is the
+  backstop, and a SIGKILLed clone does NOT clean up after itself the way a failed one
+  does, so the endpoint removes the target on any non-zero exit.
+- **Local projects only.** A clone on a remote host would run over SSH; the remote flow
+  already takes an existing path.
+
 ### Open in VS Code (issue #63)
 
 `editor-links.js` builds the links; `POST /api/editor/open` decides which of the two
@@ -986,7 +1012,7 @@ message replays the chat's history into a fresh Claude session rather than losin
 
 ## How to Verify Changes
 
-`npm test` runs 79 test files under `test/` (19 `test/render/*.test.mjs` + 60 `test/*.test.js`), and `.github/workflows/ci.yml` runs the same command on every push and PR to `main`. Nothing covers the live browser/WebSocket path, so also verify that manually:
+`npm test` runs 80 test files under `test/` (19 `test/render/*.test.mjs` + 61 `test/*.test.js`), and `.github/workflows/ci.yml` runs the same command on every push and PR to `main`. Nothing covers the live browser/WebSocket path, so also verify that manually:
 
 ```bash
 # 1. Start server

git-clone.js

@@ -0,0 +1,71 @@
+// git-clone.js — "Add project from a Git URL" (issue #94): the pure half.
+//
+// POST /api/projects/clone in server.js takes a URL and a parent directory the
+// user has already browsed to, runs `git clone` into <parent>/<repo>, and registers
+// the result as a local project. Everything that can be decided without touching
+// the filesystem or spawning git lives here so it is testable in isolation.
+//
+// Three rules, each of which exists because the URL and the names are user input
+// that end up in a process argv and in a path we create:
+//
+// - TRANSPORTS ARE AN ALLOWLIST. `ext::` runs an arbitrary command, `file://` and a
+//   bare local path clone any repository this process can read — neither is a URL a
+//   project should be created from. The same list is exported as GIT_ALLOW_PROTOCOL
+//   so a redirect or a submodule cannot widen it after the check.
+// - NOTHING WE PASS MAY LOOK LIKE AN OPTION. The URL and the target follow `--`, but
+//   `--branch <b>` cannot, so a branch starting with `-` is refused outright rather
+//   than reaching git as a second flag.
+// - THE DIRECTORY NAME IS A SINGLE PATH SEGMENT. Derived from the URL or given by
+//   the user, it is joined onto a parent that passed isPathAllowed(); `..`, `/` or a
+//   leading `.` would let the clone land somewhere else.
+
+const ALLOWED_PROTOCOLS = ['http', 'https', 'ssh', 'git'];
+
+// A directory we will create — one segment, no leading dot, no separators.
+const DIR_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+// git's own rules are looser (check-ref-format), but a branch outside this set is
+// far more likely a typo or an injection attempt than a real ref name.
+const BRANCH_RE = /^[A-Za-z0-9][A-Za-z0-9._/-]*$/;
+
+const URL_RE = /^(?:https?|ssh|git):\/\/[^\s/@]+(?:@[^\s/@]+)?(?::\d+)?\/[^\s]+$/;
+// scp-like: git@github.com:user/repo.git — no scheme, exactly one ':' after the host.
+const SCP_RE = /^[A-Za-z0-9._-]+@[A-Za-z0-9._-]+:[^\s:]+$/;
+
+/**
+ * @param {unknown} raw
+ * @returns {{ url: string, repoName: string } | null} null when the URL is not one
+ *   we clone from; repoName is the last path segment minus `.git`.
+ */
+function parseCloneUrl(raw) {
+  if (typeof raw !== 'string') return null;
+  const url = raw.trim();
+  if (!url || url.startsWith('-') || /[\s\0]/.test(url)) return null;
+  if (!URL_RE.test(url) && !SCP_RE.test(url)) return null;
+  const tail = url.replace(/\/+$/, '').split(/[/:]/).pop().replace(/\.git$/i, '');
+  if (!DIR_NAME_RE.test(tail)) return null;
+  return { url, repoName: tail };
+}
+
+function isValidDirName(s) {
+  return typeof s === 'string' && DIR_NAME_RE.test(s);
+}
+
+function isValidBranch(s) {
+  return typeof s === 'string' && BRANCH_RE.test(s) && !s.includes('..') && !s.endsWith('/');
+}
+
+/** argv for `git`, after the binary. */
+function cloneArgs({ url, target, branch = '', shallow = false }) {
+  const a = ['clone'];
+  if (branch) a.push('--branch', branch);
+  if (shallow) a.push('--depth', '1');
+  a.push('--', url, target);
+  return a;
+}
+
+/** Environment for the clone: never prompt, never widen the transport list. */
+function cloneEnv(base = process.env) {
+  return { ...base, GIT_TERMINAL_PROMPT: '0', GIT_ALLOW_PROTOCOL: ALLOWED_PROTOCOLS.join(':') };
+}
+
+module.exports = { ALLOWED_PROTOCOLS, parseCloneUrl, isValidDirName, isValidBranch, cloneArgs, cloneEnv };