@pipod/cli 0.0.0-stage → 0.1.4

package/docs/workspace-seeding.md

@@ -0,0 +1,106 @@
+# Workspace seeding
+
+A pod's workdir starts empty. Init scripts (org, template, user) fill it for configured
+projects; for everything else, `pipod` seeds the fresh pod from the directory it was launched in.
+
+## When a launch seeds
+
+The clone-or-archive workflow runs only for a **source-less launch**: no `.pi-pod/config.json`
+is found in the launch directory or any parent up to `$HOME` (the same upward lookup every
+other command uses, so `repo/src/` still belongs to `repo/`). It never runs when:
+
+| Situation | Behavior |
+|---|---|
+| `.pi-pod/config.json` found | unchanged: the project tree is copied over `/pods/:id/files` when no template init script exists |
+| `pipod fork <pod>` | the conversation is copied, never the workspace |
+| a stopped pod is reused (`--reuse` only; the `reuse` config key is retired) | the warm disk keeps its own workspace |
+| `--on <pod\|self>` | a co-located pod shares its host's workdir |
+| `--no-seed` | the pod starts empty |
+
+The **seed root** is `git rev-parse --show-toplevel` when the launch directory is inside a
+work tree, otherwise the directory itself. `/` and the home directory are refused. Launching
+from a subdirectory seeds the whole repository and prints the subdirectory so it is not a surprise.
+
+## Clone or archive
+
+A clone is chosen only when it reproduces the host checkout exactly. Every check below fails
+closed into an archive with a human-readable reason (`pipod --dry-run` prints it):
+
+1. inside a git work tree
+2. `origin` exists and rewrites to an `https://` URL (`git@host:x/y.git` and `ssh://` are rewritten; local paths cannot be cloned by a pod)
+3. HEAD is on a branch
+4. no modified, staged, or untracked non-ignored files
+5. the branch has an upstream with no unpushed commits
+6. no initialized submodules, no Git LFS attributes
+7. the pod's egress policy admits the remote host
+8. a live `git ls-remote` shows the remote branch at exactly the local HEAD commit
+
+The server clones that exact commit into the empty workdir. If the clone fails for any
+reason, the launch automatically falls back to an archive of the local tree.
+
+An **archive** is a gzip-compressed POSIX tar stream written to a temporary file and streamed
+to `PUT /v1/pods/:id/workspace/archive`. It contains tracked and untracked non-ignored files,
+directory and file modes, and symlinks that stay inside the tree. It excludes git-ignored
+paths, `node_modules`, `.pi-pod/env`, sockets/FIFOs/devices, and symlinks that are absolute
+or escape the tree. `.git` is included when it is a real directory (with credentials stripped
+from `.git/config` URLs) so dirty and unpushed repositories arrive as repositories; when the
+archive would exceed the size cap, the launch retries without history and says so.
+
+Default client-side caps: 256 MiB compressed, 2 GiB uncompressed, 200,000 entries.
+
+## Credentials
+
+- Anonymous access is tried first with every prompt disabled.
+- For a private remote, the host's `git credential fill` is consulted, then `gh auth token`.
+- The credential is verified with a second `ls-remote` before anyone is asked anything.
+- **You are asked before a token is forwarded.** `--yes` approves the prompt; declining, or a
+  non-interactive launch without `--yes`, sends an archive instead.
+- The token travels once in the clone request body, is used for that clone, and is never
+  written to pod metadata, resolved configuration, audit rows, command arguments, logs, or
+  files inside the pod. SSH keys are never forwarded.
+- `--dry-run` and `pipod doctor` never read credentials; they report "would clone with
+  forwarded credentials if they work".
+
+## Pi starts after the seed
+
+A seeding launch sends `workspaceSeed: true` in the launch body. The server provisions the
+sandbox, reports the pod ready, and holds Pi until the clone or archive route records a
+successful seed. When the client ends up not seeding (nothing to send, an oversized tree, a
+failed transfer, an already-populated workdir), it posts to `/pods/:id/workspace/skip` so Pi
+starts at once; the server also opens the gate on its own after a timeout, so a client that
+dies mid-seed never strands the pod. Configured projects keep their post-start copy and do not
+arm the gate.
+
+## Older servers
+
+A server with a strict launch schema rejects the `workspaceSeed` flag; the client retries the
+launch without it and Pi starts immediately, as before. When the workspace routes are missing
+(404), a tree under the 24 MiB `/files` limit is copied entry by entry; a larger tree is
+reported and the pod starts empty. `pipod send <path>` fills it afterwards.
+
+## Manual testing
+
+Follow the pi-pod CLI manual-testing technique (build the checkout, invoke `node dist/cli.js`,
+drive the TUI from tmux, archive every pod you create). Cases worth a real pod
+on the sandbox backend:
+
+1. **Public clone** — `cd` into a clean, pushed clone of a public repository with no
+   `.pi-pod/`, run `node <repo>/dist/cli.js`. Expect `workspace seed: the pod will clone …`,
+   then `!git log -1` inside the pod shows the same commit and `!git status` is clean.
+2. **Private GitHub clone** — same with a private repository and `gh auth login` done. Expect
+   the forwarding prompt; approve; `!git remote -v` inside the pod shows the https URL with no
+   token, and `!cat .git/config` holds no token.
+3. **Declined forwarding** — answer `n`; expect an archive, and the pod still holds the tree.
+4. **Dirty repository archive** — edit a file, launch; expect `will be archived … (uncommitted
+   changes would be lost by a clone)` and `!git status` in the pod shows the same edit.
+5. **Non-git archive** — a plain directory of files; expect the files without a `.git`.
+6. **100+ MiB streaming archive** — a repository with a large untracked binary; watch the
+   `upload 25% …` lines; verify the file's checksum in the pod.
+7. **Interrupted upload** — Ctrl-C during upload; expect the pod deleted and no
+   `pi-pod-seed-*.tar.gz` left in the temp directory.
+8. **Nested pod launch** — from inside a pod, launch a child from a source-less directory;
+   symlinks are skipped with a warning, files arrive.
+9. **Template/init-script collision** — `--template <one whose init script clones>`; expect
+   `workspace already populated … leaving it in place`.
+10. **`--no-seed`, `--dry-run`, `fork`, `--on`** — none create a transfer; `--dry-run` prints
+    the decision and creates no pod.

package/image/Dockerfile

@@ -0,0 +1,65 @@
+# image/Dockerfile  (built via: pi-pod image build)
+#
+# The canonical artifact is a plain OCI image (§12). Each adapter maps it to its provider's
+# native form — Daytona ingests it as a snapshot. One Dockerfile, every provider.
+#
+# Pinned to a specific Debian release rather than a floating tag, so a rebuild of the same
+# image tag is reproducible. If your organization forbids direct pulls from public
+# registries, repoint this one line at your mirror — it is the only registry reference in
+# the whole repo.
+FROM node:22-bookworm-slim
+
+# build-essential is here for pi extensions with native dependencies (§7.5). Those normally
+# install a prebuilt binary and never touch a compiler — but when no prebuild matches this
+# platform and Node ABI, npm falls back to node-gyp, and without a toolchain that fallback
+# fails at compile time. It failed *earlier* than that until recently, because node-gyp could
+# not reach nodejs.org for headers either; fixing only the egress side would have moved the
+# error from "cannot fetch headers" to "no such file or directory: make", which is not better.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+      bash ca-certificates git gh ripgrep jq curl openssh-client python3 python3-pip \
+      tmux procps \
+      build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+ARG PI_VERSION=latest
+# no --ignore-scripts: TUI deps (e.g. node-pty) may need postinstall native builds
+RUN npm install -g @earendil-works/pi-coding-agent@${PI_VERSION}
+
+
+# pi extension packages (§7.5), one `npm:`-style source per line. Empty for an image built
+# without them, in which case this is a no-op layer.
+#
+# Installed here rather than at session start because it is the same bytes every time — ~450 MB
+# and a native-module build for a representative list. The tag carries a digest of this file,
+# so an image and its package set cannot disagree.
+#
+# Built *in* the image rather than copied from the host on purpose: this list pulls in native
+# modules, and a host `node_modules` is compiled for the developer's own platform (typically
+# darwin/arm64). Those binaries do not load here, and would fail as a confusing require error
+# rather than as a missing package.
+# pi-packages.txt is the full source list (provenance; the tag digests it). The launcher
+# also writes pi-packages-npm.txt with only the resolved npm specs, one per line, so this
+# step needs no sed/grep filtering — template builders (E2B) re-parse the Dockerfile and
+# have mangled regex escapes in that pipeline before, silently baking zero packages.
+COPY pi-packages.txt /usr/local/share/pi-pod/pi-packages.txt
+COPY pi-packages-npm.txt /usr/local/share/pi-pod/pi-packages-npm.txt
+RUN if [ -s /usr/local/share/pi-pod/pi-packages-npm.txt ]; then \
+      mkdir -p /root/.pi/agent/npm && \
+      xargs --no-run-if-empty npm install --prefix /root/.pi/agent/npm --legacy-peer-deps \
+        < /usr/local/share/pi-pod/pi-packages-npm.txt; \
+    fi
+
+# Bake script: the org/template/project `bake.sh` layers, composed by the launcher into one
+# file (empty for an image built without one, in which case both steps are no-op layers).
+# The tag carries a digest of this file, so editing any bake layer derives a new image
+# rather than mutating this one. Deliberately the last layer: a bake edit re-uses every
+# layer above it. Runs with no secrets and no /workspace — an image build has neither, and
+# the launcher's live fallback run of the same script matches that on purpose, so a bake
+# script that depends on either fails the same way on both paths.
+COPY bake.sh /usr/local/share/pi-pod/bake.sh
+RUN if [ -s /usr/local/share/pi-pod/bake.sh ]; then \
+      cd /root && CI=1 DEBIAN_FRONTEND=noninteractive bash /usr/local/share/pi-pod/bake.sh; \
+    fi
+
+ENV DEBIAN_FRONTEND=noninteractive
+WORKDIR /workspace

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@pipod/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.4",
+  "description": "Run pi coding-agent sessions in server-managed pods",
+  "type": "module",
+  "license": "AGPL-3.0-only",
+  "homepage": "https://pipod.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pi-pod/pipod.git",
+    "directory": "cli"
+  },
+  "bugs": "https://github.com/pi-pod/pipod/issues",
+  "bin": {
+    "pipod": "dist/cli.js",
+    "pp": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "image",
+    "docs",
+    "templates"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "lint": "node --import tsx scripts/check-runtime-surface.ts",
+    "test:integration": "node --import tsx --test --test-concurrency=1 test/integration/account-cli.test.ts test/integration/account-login-me-http.test.ts test/integration/billing-cli.test.ts test/integration/capacity-wait-http.test.ts test/integration/cli-main.test.ts test/integration/local-extensions.test.ts test/integration/nested-pods.test.ts test/integration/oidc-security.test.ts test/integration/secrets-cli.test.ts test/integration/workspace-seeding.test.ts test/integration/workstation-wake-http.test.ts",
+    "check": "npm run lint && npm run typecheck",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@earendil-works/pi-coding-agent": "0.84.4",
+    "@earendil-works/pi-tui": "0.84.4",
+    "cron-parser": "^5.10.0",
+    "jose": "^5.10.0",
+    "ws": "^8.22.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "@types/ws": "^8.18.1",
+    "tsup": "^8.3.5",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  }
+}

package/templates/user-config.jsonc

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://example.invalid/pi-pod/config.schema.json",
+
+  // ~/.pi-pod/config.json contains client preferences only. Pod settings belong in an
+  // organization default, a named template, or the project's .pi-pod/config.json.
+  // "template": "web-dev",
+
+  // Resolve op:// references in local project env files via the 1Password CLI.
+  // "secretResolver": { "type": "1password" },
+
+  "pi": {
+    "chords": {
+      "enabled": true,
+      "prefix": "ctrl+\\",
+      "bindings": {
+        "d": "detach",
+        "a": "archive",
+        "s": "status",
+        "l": "list",
+        "w": "switch"
+      }
+    },
+    "sessionNaming": "auto"
+  }
+}