dsh-gh-pages-artifacts 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VibOtaku
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,227 @@
+# dsh-gh-pages-artifacts
+
+A [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh) plugin that lets agents publish **artifacts** (HTML pages and Markdown documents) as shareable links on **GitHub Pages**.
+
+Ask the agent for a report, dashboard, chart, or write-up "as a page". It writes the file, publishes it, and replies with a link like `https://you.github.io/dsh-artifacts/q3-report-k3x9ab/`. Later it can update the same artifact in place, so the link never changes. It can also list, read back, and delete artifacts.
+
+> **Published artifacts are public.** GitHub Pages sites are reachable by anyone with the link. On GitHub Free the repository must be public too, and git history keeps old versions even after deletion. The plugin asks before publishing or deleting (except in *Full access* sessions, see [Behaviour details](#behaviour-details)), adds `noindex`, and refuses hidden files and content that looks like a credential, but you decide what gets shared.
+
+## What the agent gets
+
+| Tool | What it does | Approval |
+|---|---|---|
+| `artifact_publish` | Create an artifact from a workspace file (`path`) or inline `content`, or update one in place (`id`). Markdown is rendered to a clean page with light and dark themes; HTML is served as-is. Extra files (images, CSS, JS, data) go in `assets`. | yes |
+| `artifact_list` | List artifacts, newest first, with ids, titles, URLs; filter with `query`. | no |
+| `artifact_read` | Read an artifact's source (or another text file of it) in windows. | no |
+| `artifact_delete` | Delete an artifact. Its id is never reused, so an old link can't show new content. | yes |
+| `artifact_status` | Diagnose the setup (token, repository, Pages settings) and check whether a deployment or artifact is live. | no |
+| `artifact_repository` | Show or change where new artifacts go: link an existing repository (`owner/name` or a remote URL), unlink it, or switch between the shared and per-artifact strategies. | no |
+
+The plugin also adds:
+
+- a short system-prompt section so the model knows when to use the tools, and
+- a bundled `artifact-pages` skill with page-design guidance. Users can invoke it as `/artifact-pages`, and a same-named skill in `~/.dsh/skills` or the project overrides it.
+
+## Repository strategies
+
+- **`shared`** (default): every artifact gets a folder in one repository, at `https://<owner>.github.io/<repo>/<id>/`. The repository is, in order: one you **linked** at runtime (*"publish my artifacts to github.com/me/team-pages"*, which the agent does with `artifact_repository` `link`), the `repository` option (`owner/name` or a remote URL such as `git@github.com:me/team-pages.git`), or `owner`/`repo`.
+- **`per-artifact`**: each new artifact gets a **new repository** of its own, `<owner>/<repoPrefix><id>` (default `artifact-<id>`), served at `https://<owner>.github.io/artifact-<id>/`. The plugin creates the repository, publishes the page at its root, turns on GitHub Pages, tags it with the `dsh-artifact` topic, and sets the page URL as the repository's homepage. This needs a token that may create repositories (see the token section).
+
+Set it on the plugin's settings page, with the `repoStrategy` option, or in chat (*"from now on, put each artifact in its own repo"*). A choice made in chat is saved into the same settings, so the settings page and your profile file always show what is in effect. (Without dsh's settings service, for example in a custom composition, the choice is kept in the registry instead and overrides the configuration.) Existing artifacts always stay where they were published; updates, reads, and deletes find them through the registry.
+
+## Tracking what was published
+
+Click **Artifacts** in the dsh sidebar (Web and Desktop) to see every published page and document, newest first. Each entry shows its title, link, description, repository, and last update. Links open in a new browser tab (on Desktop, in your default browser). **Refresh** also checks GitHub for artifacts published from another machine. To delete one, hover its row, click the trash icon, and confirm. The plugin commits the removal of its files from the repository and tombstones its id, and the page returns 404 once GitHub Pages redeploys (usually within a minute). Because you confirmed in the panel yourself, the agent approval prompt does not apply here.
+
+Every publish, update, and delete is recorded in a local registry at `$DSH_HOME/gh-pages-artifacts/registry.json` (option `registryDir`). Next to it, `index.html` lists every artifact with **clickable links** to its page and repository, its kind, revision, last update, and whether it is live or deleted. `artifact_list` returns the same list as Markdown links, across all repositories and strategies, and adds artifacts it finds in the shared repository that were published from another machine. Ask *"what have you published?"* or *"show me the artifact index"* (the agent can present the index page in the side panel).
+
+## How it works
+
+- **The repository holds the content.** Each artifact lives in its own folder on the Pages branch (or at the root of its own repository with the per-artifact strategy) (`<id>/index.html`, plus `source.md` for Markdown and any assets). A manifest `.dsh-artifacts.json` at the branch root records ids, titles, descriptions, kinds, revisions, and timestamps. With `siteDir: ''` (the default) the manifest is served too, so anyone who knows the site URL can list every artifact. Publish from `/docs` (`siteDir: docs`) to keep it unlisted.
+- **Every change is one atomic commit.** The commit is built with the Git Data API (blobs → tree → commit) and applied with a fast-forward-only ref update. If another writer (a second dsh window, another machine) moved the branch, the change is rebuilt on the new head and retried. Nothing is lost, and nothing is force-pushed.
+- **`.nojekyll`** is committed so Pages serves files exactly as written. The plugin refuses to write into an existing Jekyll site (one with `_config.yml` and no `.nojekyll`), and it cannot publish to a protected branch.
+- **URLs** are `<site>/<pathPrefix>/<id>/`. The site URL comes from the Pages API, which handles custom domains; set `baseUrl` to override it. Ids are a slug of the title plus a random suffix (`q3-report-k3x9ab`), or a `slug` you choose.
+- **Pages caching:** a change is usually live within a minute. Browsers may keep the previous version for up to 10 minutes.
+
+## Requirements
+
+- DeepSeek Harness **0.2.0-rc.2 or newer, within 0.2.x** (Web, Desktop, or CLI).
+- A GitHub account and a repository with GitHub Pages enabled (the setup command below does this for you).
+- A GitHub token with **Contents: read and write** (and preferably **Pages: read-only**) on that repository only. The per-artifact strategy needs a token that may create repositories instead (see below).
+
+## Setup
+
+### 1. Create the repository and enable Pages
+
+Run this yourself in a terminal (not through the agent), from a checkout of this repository, with the [GitHub CLI](https://cli.github.com) logged in (`gh auth login`):
+
+```bash
+node bin/setup.mjs setup --author "Your Name <you@example.com>"
+```
+
+It creates a **public** repository `dsh-artifacts` under your account (asking first), creates the `gh-pages` branch, and enables GitHub Pages from it. `--author` sets the author of the commits it makes; without it GitHub uses your account's identity. Other options: `--owner <org>`, `--repo <name>`, `--branch <name>`, `--docs` (publish from `/docs`), `--private` (paid plans only; implies `--docs`; the pages are still public), and `--yes`. Once the package is published to npm, `npx dsh-gh-pages-artifacts setup` does the same.
+
+To do it by hand instead:
+
+1. Create a repository, for example `dsh-artifacts`. Do **not** use your `<you>.github.io` site repository, because artifacts would share its root.
+2. In **Settings → Pages**, choose **Deploy from a branch**, then branch `gh-pages` and folder `/ (root)`. If the branch does not exist yet, the plugin creates it on first publish; pushing a `gh-pages` branch usually enables Pages automatically.
+
+### 2. Create a token
+
+Create a [fine-grained personal access token](https://github.com/settings/personal-access-tokens/new):
+
+- **Repository access:** Only select repositories → your artifacts repository
+- **Permissions:**
+  - **Contents:** Read and write (required)
+  - **Pages:** Read-only (recommended; lets `artifact_status` verify the Pages settings and deployments, and lets the plugin discover custom domains)
+
+A classic token with the `public_repo` scope also works but grants far more access. Avoid reusing `gh auth token`: it carries all of your CLI's scopes.
+
+For the **per-artifact** strategy the token must create repositories and turn on Pages: a fine-grained token with **Repository access: All repositories** and **Administration**, **Contents**, and **Pages** set to *Read and write*, or a classic token with `public_repo` (or `repo` for private repositories).
+
+### 3. Give the token to dsh
+
+The plugin reads the credential named by `tokenEnv` (default **`GH_PAGES_TOKEN`**). It never takes the token from the conversation. **Never paste it into a chat.** Use any one of these sources (highest precedence first):
+
+1. **Environment** of the process that launches dsh: `export GH_PAGES_TOKEN=github_pat_...`. Desktop on macOS and Linux imports your login shell's exports at start, so restart the app after changing them.
+2. **`$DSH_HOME/.credentials.yaml`** (default `~/.dsh/.credentials.yaml`). It hot-reloads and must be `chmod 600`:
+
+   ```yaml
+   version: 1
+   refs:
+     GH_PAGES_TOKEN: github_pat_...
+   ```
+
+   If the file already exists, add the key under its existing `refs:`. Don't add a second `refs:`.
+3. A `.env` in the directory you launched dsh from. It is read once at launch, so restart after editing it. If the token comes from here, the plugin requires the `owner` option, so a repository's own `.env` can't silently redirect your publishes to someone else's account.
+4. `$DSH_HOME/.env`. Also read at launch, so restart after editing it.
+
+A value from the environment wins and is read-only. Token-shaped variable names (containing `TOKEN`) are scrubbed from the agent's shell commands. The agent's processes run as your OS user, though, so treat this as discretion, not a security boundary.
+
+### 4. Install the plugin
+
+**From the latest release** (recommended; prebuilt, so nothing is built on your machine):
+
+```bash
+dsh plugin --profile web add https://github.com/opdsh/dsh-gh-pages-artifacts/releases/latest/download/dsh-gh-pages-artifacts.tgz
+```
+
+On **Desktop / Web**, open **Plugins → Add plugin** and enter the same URL. Restart running CLI profiles after installing.
+
+**From source on GitHub.** The package builds itself on install, so pnpm blocks the first attempt until you allow that build:
+
+```bash
+dsh plugin --profile web add github:opdsh/dsh-gh-pages-artifacts
+```
+
+dsh then prints a key like `dsh-gh-pages-artifacts@https://codeload.github.com/opdsh/dsh-gh-pages-artifacts/tar.gz/<commit>`. Add it with `: true` under `allowBuilds:` in the profile's `pnpm-workspace.yaml` (dsh prints the path), then run the command again. The key names one commit, so allow it again after updating.
+
+**From a local checkout.** Build it first (`lib/` is not committed):
+
+```bash
+git clone https://github.com/opdsh/dsh-gh-pages-artifacts.git
+```
+
+```bash
+cd dsh-gh-pages-artifacts && pnpm install && pnpm run build
+```
+
+```bash
+dsh plugin --profile web add "$PWD"
+```
+
+### 5. Configure it (optional)
+
+Open **Plugins → GitHub Pages Artifacts**. The plugin's page has its settings:
+
+- **GitHub token:** whether one is configured, and a field that saves it to dsh's credential store (not available when the token comes from the environment)
+- **Where artifacts are published:** the strategy, the shared repository (`owner/name` or a remote URL), the owner, prefix, and visibility of new repositories, and the Pages branch
+- **Commits:** the author name and email
+- **Safety:** approval, `noindex`, and secret blocking
+
+Changes apply to the next publish without a restart, and are saved to your profile's `cordis.patch.yml`.
+
+You can also edit that file directly. The defaults work when the repository is `dsh-artifacts` under the token's user and Pages publishes `gh-pages` from the root; otherwise add a row like this:
+
+- CLI: `~/.dsh/profiles/<profile>/cordis.patch.yml`
+- Desktop: **Settings → Open configuration file**
+
+```yaml
+- id: gh-pages-artifacts
+  config:
+    owner: your-login-or-org
+    repo: dsh-artifacts
+```
+
+A patch replaces the row's whole `config`, and any key you leave out uses its default. Check the composed result with `dsh --profile web --dump-config`. Changes reload live in the Web and Desktop apps.
+
+Then ask the agent: *"Make a one-page summary of this repo's architecture and publish it."* If anything is off, ask it to run `artifact_status`.
+
+## Configuration reference
+
+| Option | Default | Meaning |
+|---|---|---|
+| `owner` | token's user | User or organization that owns the repository. |
+| `repo` | `dsh-artifacts` | Repository that hosts artifacts. |
+| `repository` | none | The shared repository as `owner/name` or a remote URL (`https://github.com/owner/name.git`, `git@github.com:owner/name.git`); overrides `owner`/`repo` for it. A repository linked at runtime overrides this. |
+| `repoStrategy` | `shared` | `shared` (one repository) or `per-artifact` (a new repository for each new artifact). A runtime choice overrides this. |
+| `repoPrefix` | `artifact-` | Name prefix of repositories the per-artifact strategy creates. |
+| `repoVisibility` | `public` | Visibility of repositories the per-artifact strategy creates. Pages on private repositories needs a paid plan; the pages are public either way. |
+| `registryDir` | `$DSH_HOME/gh-pages-artifacts` | Folder for the local registry and its `index.html`. |
+| `branch` | `gh-pages` | Branch Pages publishes from. Created on first publish when missing. |
+| `siteDir` | `''` | Pages source folder: `''` (root) or `docs`. |
+| `pathPrefix` | `''` | Folder under the site root for artifacts, e.g. `a` → `<site>/a/<id>/`. |
+| `baseUrl` | from the Pages API | Public site URL. Set it for custom domains when the token lacks Pages read, and on GitHub Enterprise Server (required there unless the token can read Pages). |
+| `tokenEnv` | `GH_PAGES_TOKEN` | Credential reference (environment variable name) holding the token. |
+| `apiBaseUrl` | `https://api.github.com` | REST API base; change it only for GitHub Enterprise Server. |
+| `approval` | `unless-full-access` | `unless-full-access`: ask before publish and delete, except in *Full access* sessions (danger-full-access sandbox with approval prompts turned off). `always`: always ask. `off`: never ask. |
+| `hideFromPresets` | `['minimal']` | Agent modes that don't get the artifact tools. |
+| `subagentAccess` | `read-only` | Delegated subagents: `read-only` (list, read, status), `full`, or `none`. |
+| `noindex` | `true` | Add `<meta name="robots" content="noindex, nofollow">` to pages, even if the page asks to be indexed. |
+| `csp` | `object-src 'none'; base-uri 'none'` | Content-Security-Policy meta tag added to pages; `''` disables it. |
+| `blockSecrets` | `true` | Refuse hidden and credential files (`.env`, keys, `.ssh/`, ...) and any title, description, page, or asset that looks like a credential (GitHub/AWS/Slack/npm/API keys, JWTs, private keys, passwords in URLs or assignments, the configured token in any common encoding). |
+| `maxPublishBytes` | `10485760` | Maximum total bytes of one publish (page plus assets). |
+| `commitAuthor` | token's user | `{ name, email }` used as commit author and committer. |
+| `promptGuidance` | `true` | Add the short system-prompt section. |
+| `bundledSkill` | `true` | Register the `artifact-pages` skill. |
+
+## Behaviour details
+
+- **Approval.** Publish, update, and delete ask through the dsh approval panel. The prompt leads with the exact URL and lists the source file (or inline content size), every asset as `source → published name`, removed assets, and the total size. Titles are quoted and may not contain control or bidi characters, so they can't disguise the request. With the default `unless-full-access`, only *Full access* sessions publish without a prompt; *Auto* sessions are still asked. Headless runs and SDK sessions without an approval channel fail closed unless you set `approval: off`. Subagents cannot ask for approval, so by default they only get the read-only tools; this is enforced when the tools run, not just by hiding them.
+- **Workspace confinement.** `path` and `assets` must be regular files inside the session's working directory. Symlinks, directories, paths that resolve outside it, hidden files, and credential-looking files are refused. The page itself must be `.html`, `.htm`, `.md`, `.markdown`, or `.txt`. This blocks path tricks, but it cannot stop an agent from copying data into the workspace or passing it inline. The approval prompt, and you, remain the real control.
+- **Markdown** is rendered with GitHub-flavored Markdown (tables, task lists, footnotes, strikethrough, autolinks). Raw HTML inside Markdown is escaped and `javascript:` links are dropped. Publish HTML for anything interactive.
+- **HTML** is published as written. A fragment is wrapped into a complete document. The plugin inserts only the robots and CSP meta tags right after `<head>`, marked with `data-dsh-artifacts` so `artifact_read` returns the page without them. Inline `content` counts as HTML only when it is a whole document (`<!doctype html>` or `<html>`); anything else is rendered as Markdown.
+- **Updates** replace the page, keep assets you don't mention, and remove those listed in `removeAssets`. Pass `baseRev` to refuse an update when someone else changed the artifact since you read it.
+- **Delete** removes the files from the branch head and tombstones the id. The content stays in git history, and anyone who saved a copy keeps it.
+- **Status.** `artifact_status` compares the latest Pages build with the branch head, so "deployed" means your newest change is live. With `wait: true` it waits up to five minutes. Real deployments usually take one to three minutes.
+- **Origin isolation.** All project sites of one owner share the `https://<owner>.github.io` origin (cookies, localStorage). If you run other apps on that origin, consider a separate account or organization, or a custom domain, for artifacts.
+
+## Development
+
+Releases are cut by pushing a tag that matches `package.json` (for example `v0.1.0`); the release workflow tests, builds, and attaches `dsh-gh-pages-artifacts.tgz` to the GitHub Release.
+
+```bash
+pnpm install
+pnpm run typecheck
+pnpm test          # unit, integration (real dsh tool/approval/fs/skill services), and setup-script tests against an in-memory GitHub
+pnpm run build     # emits lib/
+```
+
+To try a local checkout without installing it, run dsh with an overlay patch:
+
+```yaml
+# dev.patch.yml
+- insert:
+    - id: gh-pages-artifacts
+      name: /absolute/path/to/gh-pages-plugin/lib/index.js
+      config:
+        owner: your-login
+```
+
+```bash
+dsh web --patch ./dev.patch.yml
+```
+
+## License
+
+MIT

package/assets/artifact-pages/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: artifact-pages
+description: Design, write, and publish polished web pages and documents as shareable GitHub Pages links with the artifact_publish tool. Use when the user asks for something to open in a browser or share by link, such as a report, dashboard, chart, interactive demo, slide-style page, or long-form document, or asks to publish, update, list, or delete a published artifact.
+---
+
+# Publishing artifacts on GitHub Pages
+
+An artifact is one HTML page (with optional asset files) or one Markdown document, published at a stable public URL. The `artifact_*` tools handle the GitHub side. Your job is to make the page worth opening.
+
+## Pick the kind
+
+- **Markdown document** (`.md`): prose-first content such as reports, write-ups, notes, guides, and READMEs. The plugin renders GitHub-flavored Markdown (tables, task lists, footnotes, code blocks) into a clean, readable page with light and dark themes. Raw HTML inside Markdown is escaped, so use plain Markdown.
+- **HTML page** (`.html`): anything visual or interactive, such as dashboards, charts, calculators, explorable explanations, slide-style pages, and landing pages. The file is served as-is.
+
+## Workflow
+
+1. Write the page to a workspace file, e.g. `report.md` or `dashboard.html`. Do not paste long sources into `content`.
+2. Check it before publishing. Render-check HTML mentally or with available tools, make sure every asset path resolves, and read the text once for accuracy.
+3. Publish: `artifact_publish({ description, title, path })`. Add `assets` for images or data files the page references by relative URL.
+4. Reply with the link as Markdown: `[Title](url)`. Mention that it can take about a minute to go live.
+5. To change it later, edit the file and call `artifact_publish({ description, id, path })` with the same `id`, so the URL stays the same. If you did not write the current version yourself, `artifact_read` it first and pass `baseRev`.
+
+Use `artifact_status` with `id` and `wait: true` when the user wants confirmation that the page is live, or when something looks wrong (missing token, Pages disabled, failed build).
+
+## Privacy and safety
+
+- Everything published is public, and the repository history keeps old versions even after deletion. Never include credentials, tokens, personal data, internal URLs, or private conversation content unless the user explicitly asked to publish exactly that.
+- Never ask the user to paste a GitHub token into the chat. The token is configured outside the conversation (see the plugin README).
+- Do not publish pages that imitate a real organization's or person's site, or forms that collect passwords or payment details.
+
+## HTML pages that look good
+
+Prefer one self-contained file: inline `<style>` and `<script>`, plus a few external libraries from a CDN when they genuinely help (for example a charting library from cdn.jsdelivr.net or cdnjs.cloudflare.com, pinned to an exact version).
+
+Structure:
+
+```html
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Clear, specific title</title>
+  <style>
+    :root { color-scheme: light dark; --bg: #fff; --fg: #1f2328; --muted: #59636e; --accent: #0969da; --border: #d1d9e0; }
+    @media (prefers-color-scheme: dark) { :root { --bg: #0d1117; --fg: #e6edf3; --muted: #9198a1; --accent: #4493f8; --border: #3d444d; } }
+    body { margin: 0; background: var(--bg); color: var(--fg); font: 16px/1.6 system-ui, sans-serif; }
+    main { max-width: 64rem; margin: 0 auto; padding: 2rem 1rem; }
+  </style>
+</head>
+<body>
+  <main>...</main>
+</body>
+</html>
+```
+
+Design rules:
+
+- Define colors once as CSS variables and support dark mode with `prefers-color-scheme`. Give `body` an explicit background.
+- Make it responsive. It must work at 360 px wide with no horizontal page scroll: use fluid widths, `max-width`, CSS grid or flex with wrapping, and `overflow-x: auto` on wide tables and code.
+- Use a clear hierarchy: one `h1`, short intro, sections with headings, generous whitespace, and a readable line length (60-80 characters).
+- Charts need titles, labeled axes with units, legends when there is more than one series, and accessible colors. Embed the data in the page (a JSON block or a JS constant) so it works offline from the CDN cache.
+- Use system fonts, or one web font if the design needs it.
+- Accessibility: semantic elements (`main`, `nav`, `section`, `button`), alt text on images, visible focus states, sufficient contrast, and keyboard-operable controls.
+- Interactive state should live in the page. Do not rely on server endpoints: GitHub Pages serves static files only.
+- Keep it fast: no huge images (compress or resize first), no autoplaying media, and lazy-load below-the-fold images.
+
+## Markdown documents that read well
+
+- Start with one `# Title` that matches the artifact title, then a one-paragraph summary.
+- Use `##` sections, short paragraphs, lists for parallel items, and tables for comparisons.
+- Use fenced code blocks with a language tag.
+- Put images in `assets` and reference them relatively: `![Revenue by month](chart.png)`.
+- End with sources or next steps when relevant.
+
+## Assets
+
+`assets: [{ path: "out/chart.png" }, { path: "data.json", name: "data/data.json" }]` publishes files next to the page. Reference them with relative URLs (`chart.png`, `data/data.json`). On update, listed assets are added or replaced and the others are kept. Use `removeAssets` to delete one. The total size of one publish is limited (10 MiB by default).
+
+## Managing artifacts
+
+- `artifact_list`: find ids and URLs, with an optional text `query`.
+- `artifact_read`: fetch the current source in windows (`offset`/`limit`) before editing someone else's version.
+- `artifact_delete`: remove a page when the user asks. The id is never reused.

package/bin/setup.mjs

@@ -0,0 +1,270 @@
+#!/usr/bin/env node
+// One-time setup for dsh-gh-pages-artifacts, run by a person (not by the agent).
+// It uses your own GitHub CLI login to create the artifacts repository, the Pages branch,
+// and the GitHub Pages site, then prints the plugin configuration and token instructions.
+import { execFileSync } from 'node:child_process'
+import { createInterface } from 'node:readline/promises'
+import { stdin, stdout, argv, env, exit } from 'node:process'
+
+const USAGE = `Usage: node bin/setup.mjs setup [options]   (or: npx dsh-gh-pages-artifacts setup)
+
+Creates (when missing) a public GitHub repository for artifacts, a Pages branch, and
+the GitHub Pages site, using your GitHub CLI ("gh") login. Nothing is changed without
+confirmation unless --yes is given.
+
+Options:
+  --owner <login>    User or organization that owns the repository (default: your gh user)
+  --repo <name>      Repository name (default: dsh-artifacts)
+  --branch <name>    Pages branch (default: gh-pages)
+  --docs             Publish from the /docs folder instead of the branch root
+  --private          Create a private repository (GitHub Pro/Team/Enterprise only;
+                     the published pages are still public). Implies --docs, so the
+                     artifact index at the branch root is not served
+  --author "Name <email>"
+                     Author and committer of the commits setup creates
+                     (default: GitHub's identity for your account)
+  --yes              Do not ask for confirmation
+  -h, --help         Show this help`
+
+function parseArgs(args) {
+  const options = { owner: undefined, repo: 'dsh-artifacts', branch: 'gh-pages', docs: false, private: false, yes: false, author: undefined }
+  const rest = [...args]
+  if (rest[0] === 'setup') rest.shift()
+  while (rest.length > 0) {
+    const arg = rest.shift()
+    const value = () => {
+      const next = rest.shift()
+      if (next === undefined || next.startsWith('--')) fail(`${arg} needs a value`)
+      return next
+    }
+    switch (arg) {
+      case '--owner': options.owner = value(); break
+      case '--repo': options.repo = value(); break
+      case '--branch': options.branch = value(); break
+      case '--docs': options.docs = true; break
+      case '--private': options.private = true; break
+      case '--author': {
+        const match = /^\s*([^<>]*?)\s*<([^\s<>@]+@[^\s<>@]+)>\s*$/.exec(value())
+        if (match === null || match[1] === '') fail('--author must look like "Name <email@example.com>"')
+        options.author = { name: match[1], email: match[2] }
+        break
+      }
+      case '--yes': case '-y': options.yes = true; break
+      case '-h': case '--help': console.log(USAGE); exit(0); break
+      default: fail(`unknown option ${arg}\n\n${USAGE}`)
+    }
+  }
+  if (options.private) options.docs = true
+  if (!/^[A-Za-z0-9._-]{1,100}$/.test(options.repo)) fail(`invalid repository name ${options.repo}`)
+  if (options.owner !== undefined && !/^[A-Za-z0-9-]{1,39}$/.test(options.owner)) fail(`invalid owner ${options.owner}`)
+  if (!/^[A-Za-z0-9._/-]{1,200}$/.test(options.branch) || options.branch.includes('..')) fail(`invalid branch ${options.branch}`)
+  return options
+}
+
+function fail(message) {
+  console.error(`error: ${message}`)
+  exit(1)
+}
+
+/** Environment for gh: plain, uncoloured, unpaged output whatever the user's shell forces. */
+const GH_ENV = (() => {
+  const clean = { ...env, CLICOLOR_FORCE: '0', NO_COLOR: '1', GH_PAGER: 'cat', GH_NO_UPDATE_NOTIFIER: '1', GH_PROMPT_DISABLED: '1' }
+  delete clean.GH_FORCE_TTY
+  return clean
+})()
+
+/** Run `gh api`; returns { ok, status, data }. Never prints the token. */
+function ghApi(method, path, body) {
+  const args = ['api', '-X', method, '-H', 'Accept: application/vnd.github+json', '-H', 'X-GitHub-Api-Version: 2022-11-28', '-i', path]
+  if (body !== undefined) args.push('--input', '-')
+  let output
+  try {
+    output = execFileSync('gh', args, { input: body === undefined ? undefined : JSON.stringify(body), encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'], env: GH_ENV })
+  } catch (error) {
+    if (error.code === 'ENOENT') fail('the GitHub CLI (gh) is not installed; get it from https://cli.github.com and run "gh auth login"')
+    output = `${error.stdout ?? ''}`
+    if (output === '') fail(`gh api ${method} ${path} failed: ${(error.stderr ?? error.message).trim()}`)
+  }
+  const split = output.search(/\r?\n\r?\n/)
+  const head = split < 0 ? output : output.slice(0, split)
+  const text = split < 0 ? '' : output.slice(split).trim()
+  const status = Number(/^HTTP\/[\d.]+ (\d{3})/m.exec(head)?.[1] ?? 0)
+  let data
+  try { data = text === '' ? undefined : JSON.parse(text) } catch { data = text }
+  return { ok: status >= 200 && status < 300, status, data }
+}
+
+/** Give a repository its first commit with a known author (auto_init would use the account's email). */
+async function initializeRepository(owner, repo, options) {
+  const readme = '# Artifacts\n\nPages published by DeepSeek Harness agents with dsh-gh-pages-artifacts. They are served from the `' + options.branch + '` branch.\n'
+  let initialized
+  for (let attempt = 0; attempt < 5; attempt++) {
+    initialized = ghApi('PUT', `/repos/${owner}/${repo}/contents/README.md`, {
+      message: 'Initialize artifacts repository',
+      content: Buffer.from(readme).toString('base64'),
+      ...authorFields(options.author),
+    })
+    if (initialized.ok || initialized.status !== 404 && initialized.status !== 409) break
+    await new Promise(resolve => setTimeout(resolve, 2000))
+  }
+  if (!initialized.ok) fail(`could not initialize ${owner}/${repo} (HTTP ${initialized.status}): ${initialized.data?.message ?? ''}`)
+}
+
+function authorFields(author) {
+  return author === undefined ? {} : { author: { ...author }, committer: { ...author } }
+}
+
+async function confirm(question, yes) {
+  if (yes) return true
+  if (!stdin.isTTY) fail('this command changes your GitHub account and must be run by a person in an interactive terminal')
+  const rl = createInterface({ input: stdin, output: stdout })
+  try {
+    const answer = (await rl.question(`${question} [y/N] `)).trim().toLowerCase()
+    return answer === 'y' || answer === 'yes'
+  } finally {
+    rl.close()
+  }
+}
+
+async function main() {
+  const options = parseArgs(argv.slice(2))
+  const me = ghApi('GET', '/user')
+  if (!me.ok || typeof me.data?.login !== 'string') {
+    fail(`could not read your GitHub user (HTTP ${me.status}); run "gh auth login" for github.com and try again`)
+  }
+  const login = me.data.login
+  const owner = options.owner ?? login
+  const ownsRepo = owner.toLowerCase() === login.toLowerCase()
+  const repo = options.repo
+  const full = `${owner}/${repo}`
+  const sitePath = options.docs ? '/docs' : '/'
+  const nojekyll = options.docs ? 'docs/.nojekyll' : '.nojekyll'
+  if (repo.toLowerCase() === `${owner.toLowerCase()}.github.io`) {
+    fail(`use a dedicated repository, not your ${repo} site: artifacts would share its root and its service-worker scope`)
+  }
+
+  // 1. Repository.
+  let repository = ghApi('GET', `/repos/${owner}/${repo}`)
+  if (repository.status === 404) {
+    const visibility = options.private ? 'PRIVATE' : 'PUBLIC'
+    if (!await confirm(`Create the ${visibility} repository ${full}?`, options.yes)) fail('cancelled')
+    const body = {
+      name: repo,
+      description: 'Artifacts published by DeepSeek Harness agents (dsh-gh-pages-artifacts)',
+      private: options.private,
+      auto_init: false,
+      has_issues: false,
+      has_projects: false,
+      has_wiki: false,
+    }
+    if (!ownsRepo) {
+      const account = ghApi('GET', `/users/${owner}`)
+      if (account.data?.type !== 'Organization') fail(`you can only create repositories under your own account (${login}) or an organization you belong to`)
+    }
+    const created = ownsRepo ? ghApi('POST', '/user/repos', body) : ghApi('POST', `/orgs/${owner}/repos`, body)
+    if (!created.ok) fail(`could not create ${full} (HTTP ${created.status}): ${created.data?.message ?? ''}`)
+    console.log(`created ${created.data.html_url}`)
+    repository = created
+    await initializeRepository(owner, repo, options)
+  } else if (!repository.ok) {
+    fail(`could not read ${full} (HTTP ${repository.status}): ${repository.data?.message ?? ''}`)
+  } else {
+    console.log(`repository ${full} exists`)
+  }
+
+  // 2. Pages branch, created as an orphan holding only .nojekyll.
+  let ref = ghApi('GET', `/repos/${owner}/${repo}/git/ref/heads/${options.branch}`)
+  if (ref.status === 409 && /empty/i.test(ref.data?.message ?? '')) {
+    // An existing repository without commits: the Git Data API needs a first commit.
+    if (!await confirm(`${full} is empty. Add a README commit so branches can be created?`, options.yes)) fail('cancelled')
+    await initializeRepository(owner, repo, options)
+    ref = ghApi('GET', `/repos/${owner}/${repo}/git/ref/heads/${options.branch}`)
+  }
+  for (let attempt = 0; ref.status === 409 && attempt < 5; attempt++) {
+    await new Promise(resolve => setTimeout(resolve, 2000))
+    ref = ghApi('GET', `/repos/${owner}/${repo}/git/ref/heads/${options.branch}`)
+  }
+  if (ref.status === 404) {
+    if (!await confirm(`Create the branch ${options.branch} in ${full}?`, options.yes)) fail('cancelled')
+    const tree = ghApi('POST', `/repos/${owner}/${repo}/git/trees`, {
+      tree: [{ path: nojekyll, mode: '100644', type: 'blob', content: '# Disables Jekyll so GitHub Pages serves files exactly as committed.\n' }],
+    })
+    if (!tree.ok) fail(`could not create the branch tree (HTTP ${tree.status}): ${tree.data?.message ?? ''}`)
+    const commit = ghApi('POST', `/repos/${owner}/${repo}/git/commits`, { message: 'Initialize GitHub Pages branch for dsh artifacts', tree: tree.data.sha, parents: [], ...authorFields(options.author) })
+    if (!commit.ok) fail(`could not create the branch commit (HTTP ${commit.status}): ${commit.data?.message ?? ''}`)
+    const created = ghApi('POST', `/repos/${owner}/${repo}/git/refs`, { ref: `refs/heads/${options.branch}`, sha: commit.data.sha })
+    if (!created.ok) fail(`could not create branch ${options.branch} (HTTP ${created.status}): ${created.data?.message ?? ''}`)
+    console.log(`created branch ${options.branch}`)
+  } else if (!ref.ok) {
+    fail(`could not read branch ${options.branch} (HTTP ${ref.status}): ${ref.data?.message ?? ''}`)
+  } else {
+    console.log(`branch ${options.branch} exists`)
+  }
+
+  // 3. GitHub Pages site, deployed from the branch.
+  let pages = ghApi('GET', `/repos/${owner}/${repo}/pages`)
+  if (pages.status === 404) {
+    if (!await confirm(`Enable GitHub Pages for ${full} from ${options.branch} ${sitePath}?`, options.yes)) fail('cancelled')
+    const created = ghApi('POST', `/repos/${owner}/${repo}/pages`, { build_type: 'legacy', source: { branch: options.branch, path: sitePath } })
+    // Pushing a gh-pages branch can enable Pages on its own, so "already enabled" (409) is fine.
+    if (!created.ok && created.status !== 409) fail(`could not enable GitHub Pages (HTTP ${created.status}): ${created.data?.message ?? ''}`)
+    pages = ghApi('GET', `/repos/${owner}/${repo}/pages`)
+    if (!pages.ok) fail(`could not read the GitHub Pages settings (HTTP ${pages.status}): ${pages.data?.message ?? ''}`)
+    console.log(created.ok ? 'enabled GitHub Pages' : 'GitHub Pages was enabled automatically')
+  }
+  if (pages.ok) {
+    const source = pages.data.source ?? {}
+    if (pages.data.build_type === 'workflow' || source.branch !== options.branch || (source.path ?? '/') !== sitePath) {
+      const current = pages.data.build_type === 'workflow' ? 'a GitHub Actions workflow' : `${source.branch} ${source.path}`
+      if (await confirm(`GitHub Pages currently publishes from ${current}. Switch it to ${options.branch} ${sitePath}?`, options.yes)) {
+        const updated = ghApi('PUT', `/repos/${owner}/${repo}/pages`, { build_type: 'legacy', source: { branch: options.branch, path: sitePath } })
+        if (!updated.ok) fail(`could not update GitHub Pages (HTTP ${updated.status}): ${updated.data?.message ?? ''}`)
+        pages = ghApi('GET', `/repos/${owner}/${repo}/pages`)
+        console.log('updated the GitHub Pages source')
+      } else {
+        console.log('left the GitHub Pages source unchanged; artifacts will not be served until it matches')
+      }
+    } else {
+      console.log('GitHub Pages is enabled')
+    }
+  } else {
+    fail(`could not read the GitHub Pages settings (HTTP ${pages.status}): ${pages.data?.message ?? ''}`)
+  }
+
+  const siteUrl = String(pages.data?.html_url ?? `https://${owner.toLowerCase()}.github.io/${repo}/`).replace(/^http:\/\/([^/]+\.github\.io)/, 'https://$1')
+  const configLines = [
+    '- id: gh-pages-artifacts',
+    '  config:',
+    `    owner: ${owner}`,
+    `    repo: ${repo}`,
+    ...options.branch === 'gh-pages' ? [] : [`    branch: ${options.branch}`],
+    ...options.docs ? ['    siteDir: docs'] : [],
+    ...options.author === undefined ? [] : ['    commitAuthor:', `      name: ${JSON.stringify(options.author.name)}`, `      email: ${options.author.email}`],
+  ]
+  console.log(`
+Done. Artifacts will be served under ${siteUrl}
+
+Next steps
+1. Create a fine-grained personal access token:
+     https://github.com/settings/personal-access-tokens/new
+   Resource owner: ${owner}
+   Repository access: Only select repositories -> ${full}
+   Repository permissions: Contents: Read and write; Pages: Read-only (recommended, for status checks)
+
+2. Give it to DeepSeek Harness as the GH_PAGES_TOKEN credential, for example in
+   $DSH_HOME/.credentials.yaml (default ~/.dsh/.credentials.yaml, chmod 600):
+
+     version: 1
+     refs:
+       GH_PAGES_TOKEN: <paste the token here, never in a chat>
+
+   or export GH_PAGES_TOKEN in the environment that launches dsh.
+
+3. Add this row to your profile's cordis.patch.yml
+   (~/.dsh/profiles/<profile>/cordis.patch.yml; Desktop: Settings -> Open configuration file):
+
+${configLines.map(line => `     ${line}`).join('\n')}
+`)
+}
+
+main().catch(error => fail(error instanceof Error ? error.message : String(error)))