@aryacode/dsh-aryacode-polish 0.3.9 → 0.5.0

package/docs/github-workspaces.md

@@ -0,0 +1,63 @@
+# GitHub workspaces
+
+**Add workspace from GitHub** turns a repository you can already reach with the
+GitHub CLI into a workspace, without a second sign-in and without storing a
+token.
+
+## What it does
+
+1. **Reads the CLI session.** The host half runs `gh auth token`. That is the
+   whole authentication story: no OAuth app, no device code, no token in a
+   settings file, no token in the browser. When `gh` is missing or signed out,
+   the dialog says so and names the command that fixes it (`gh auth login`).
+2. **Lists what that session can clone.** `GET /user/repos` with
+   `affiliation=owner,collaborator,organization_member`, paged through the
+   `link` header, most recently updated first.
+3. **Clones into your own folder.** `<home>\AryaCode\<owner>\<repo>`, created if
+   missing. A directory that is already the same repository is reused instead of
+   cloned again; a directory that is a *different* repository is an error, never
+   a silent overwrite.
+4. **Creates the workspace.** The clone path is handed to the workspace
+   controller (`workspaces.create({ path })`), which is the same call the "+" menu
+   makes, so the new workspace behaves like any other.
+
+## Where the token goes, and where it does not
+
+The token is read on the Host and passed to `git` as an `http.extraHeader` value
+in git's own environment (`GIT_CONFIG_COUNT`/`GIT_CONFIG_KEY_0`/
+`GIT_CONFIG_VALUE_0`), never in the remote URL and never on the command line — so
+it cannot leak through `ps`, a stored remote, or a shell history. GitHub's git
+server rejects a bearer token for clone, which is why the header carries
+`x-access-token` basic auth. Every line of git output is scrubbed of the token
+before it can reach the browser, and the route answers `cache-control: no-store`.
+
+## Why the entry point is the sidebar foot
+
+The "+" menu's **Add workspace** entry only appears when something occupies
+`sidebar.workspaces.directoryFlow`, and that slot is `kind: 'single'`: it already
+holds the folder picker, so occupying it would mean re-implementing folder
+choosing (browse *and* the native desktop picker) just to add a second source.
+Rather than replace the shipped picker, the feature adds its own entry in the
+sidebar foot next to it. If a multi-source workspace socket ever lands in the
+harness, only the registration moves; the route, the clone rules and the tests
+stay as they are.
+
+## Not used from the AryaAI-era plugin
+
+`@deepseek-ai/dsh-github` was read as a reference and deliberately not reused:
+it is a typert remote service with generated protocol packages, and it
+authenticates through an OAuth device flow that needs a registered OAuth app.
+Its ideas that were kept: reject anything that is not one path segment, reuse a
+checkout whose origin already matches, present the token as basic auth in git's
+environment, page the repository list, and mark a repository that is already
+cloned.
+
+## Tests
+
+`test/github.spec.mjs` covers the path rules (`.`, `..`, separators, empty),
+the destination layout, origin comparison across https/ssh forms, token
+scrubbing, the CLI token's three failure modes, signed-out and signed-in status,
+the `cloned` marker against a real temporary tree, the spawn shape of a clone
+(command, `--`, URL, destination, and the header in the environment rather than
+in the arguments), the reuse path, the refusal to overwrite another repository,
+and a failing clone whose message is scrubbed.

package/docs/workspace-folder.md

@@ -0,0 +1,73 @@
+# Open a workspace folder in the file browser
+
+## What ships
+
+A row in a Session's "…" menu: **Open workspace folder**. It resolves the workspace
+that owns the Session and asks the Host to open that directory in the platform file
+manager (Explorer on Windows, Finder on macOS, the desktop's file manager elsewhere).
+
+- Switch: `openWorkspaceFolder` (on by default).
+- Seat: `sidebar.workspaces.session.menu.item`, registered as `polish-open-folder`
+  at `order: 460`, after the shipped `session-id` row at `450`.
+- Host call: `ctx.remote.session.openWorkspacePath({ path })`, gated by
+  `ctx.remote.session.canOpenWorkspacePath()`.
+- Path source: the Workspace snapshot (`ctx.workspaces.list`), matched through
+  `WorkspaceView.sessionIds`.
+
+The row renders nothing when the switch is off, when the Session belongs to no
+workspace, or when the Host reports it cannot open a path. A menu row that cannot
+act is worse than no row.
+
+## What cannot ship, and why
+
+The requested surface was **right-click on the workspace row itself**, with a menu
+like the one AryaAI has (`Open in Explorer`, `Rename`, `Manage folders`, `Delete
+workspace`). That is not reachable from a plugin, for three independent reasons:
+
+1. The workspace row is drawn by `packages/client/ui-workspace/src/client/rows/Rows.tsx`.
+   The row element carries `data-row-key`, `role="treeitem"` and `onClick`, and has
+   no `onContextMenu`. Its "…" button opens a menu whose entries are hardcoded
+   (`rename`, `delete.workspace`).
+2. No slot exists for per-workspace menu entries. The only workspace-related list
+   slots are `sidebar.workspaces.session.menu.item` and
+   `sidebar.workspaces.session.row.action`, both scoped to a **Session** row. The
+   single `sidebar.workspaces` slot replaces the whole browser
+   (`replaceRisk: 'shadows-shipped-ui'`), which would mean rebuilding the shipped
+   sidebar.
+3. Native menus are closed to plugins: `apps/desktop/src/main.ts` allows only the
+   `application` and `edit` roles from the main window's main frame, and the
+   desktop IPC surface (`apps/desktop/src/ipc.ts`, `DshDesktopProductApi`) exposes
+   no open/reveal call.
+
+Attaching an `onContextMenu` to the row's DOM by selector would be a hack against
+private markup — the thing this bundle's ground rules forbid, and the first thing
+to break when the sidebar changes. The honest options were:
+
+- **Ship on the Session row menu** (chosen): documented slot, supported API,
+  survives harness updates.
+- Change the shell to declare `sidebar.workspaces.menu.item` and render it from the
+  workspace row, then release a harness patch. Declined: the owner wants to keep
+  taking harness updates from public releases.
+- Park the feature. Declined: the underlying capability (open a workspace folder)
+  is worth shipping now.
+
+If the harness ever declares a workspace-scoped menu slot, this feature should move
+there: the Host call and the path resolution stay exactly as they are, and only the
+registration line changes.
+
+**Owner's decision (2026-10-27):** asked again, after the Session row menu shipped,
+whether to add that slot to the harness and release a harness patch, the owner
+declined — "then forget it". The workspace row stays untouched and the feature stays
+on the Session row menu. The question has been asked and answered; do not re-open it
+without a new instruction.
+
+## Evidence for the next reader
+
+- Slot contract: `packages/client/ui-workspace/src/client/contract/slots.ts:152-205`.
+- Shipped row to copy: `packages/client/ui-workspace/src/client/session-actions/SessionId.tsx`.
+- Remote methods: `packages/api/session-controller/src/index.ts:336-339`
+  (`canOpenWorkspacePath`) and `:357-367` (`openWorkspacePath`).
+- Windows reveal path: `packages/util/native-command/src/path-opener.ts:307`
+  (`runExplorer(['/select,', …])`); `open-in-app` is mounted in the web bundle at
+  `packages/bundle/web-app/cordis.patch.yml:73-81`, so this works under `start:web`.
+- Workspace view: `packages/api/workspace-controller/src/types.ts:18-30`.

package/entries/github.js

@@ -0,0 +1,347 @@
+/**
+ * GitHub workspaces: sign in through the GitHub CLI's existing session, list
+ * repositories, and clone one under the clone root so it can be adopted as a
+ * workspace.
+ *
+ * The browser half never sees the token. It posts to one route and gets back
+ * JSON; every GitHub call and every `git` invocation happens here.
+ */
+
+import { spawn } from 'node:child_process'
+import { mkdir, realpath, stat } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+/** Absolute path the Host registers; the browser addresses `api/polish.github`. */
+export const GITHUB_ROUTE = '/api/polish.github'
+
+/** Root a clone lands in: `<home>/AryaCode/<owner>/<repo>`. */
+export function cloneRoot(home = homedir()) {
+  return join(home, 'AryaCode')
+}
+
+const SEGMENT = /^[A-Za-z0-9_.-]+$/
+
+/**
+ * Reject a repository part that could escape the clone root.
+ * @param value - owner or repository name from GitHub.
+ * @returns the same value when it is one plain path segment.
+ */
+export function assertSegment(value) {
+  if (typeof value !== 'string' || !SEGMENT.test(value) || value === '.' || value === '..') {
+    throw new Error('repository name must be a single path segment')
+  }
+  return value
+}
+
+/**
+ * Directory one repository clones into.
+ * @param owner - repository owner.
+ * @param name - repository name.
+ * @param home - home directory to root the default clone tree in.
+ * @returns absolute destination path.
+ */
+export function cloneDestination(owner, name, home = homedir()) {
+  return join(cloneRoot(home), assertSegment(owner), assertSegment(name))
+}
+
+/**
+ * Whether a git origin URL already points at this repository.
+ * @param origin - `git remote get-url origin` output.
+ * @param owner - repository owner.
+ * @param name - repository name.
+ * @returns true for either the https or the ssh form of the same repo.
+ */
+export function sameOrigin(origin, owner, name) {
+  const normalized = String(origin).trim().replace(/\.git$/i, '').replace(/\/+$/, '').toLowerCase()
+  return normalized === `https://github.com/${owner}/${name}`.toLowerCase()
+    || normalized === `git@github.com:${owner}/${name}`.toLowerCase()
+}
+
+/**
+ * Run a program and collect its output. Never throws on a non-zero exit.
+ * @param command - executable name.
+ * @param args - arguments.
+ * @param options - extra environment and working directory.
+ * @returns exit code plus captured stdout and stderr.
+ */
+export function runCommand(command, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd,
+      env: { ...process.env, GIT_TERMINAL_PROMPT: '0', GCM_INTERACTIVE: 'never', ...options.env },
+      windowsHide: true,
+    })
+    let stdout = ''
+    let stderr = ''
+    child.stdout.setEncoding('utf8')
+    child.stderr.setEncoding('utf8')
+    child.stdout.on('data', chunk => { stdout += chunk })
+    child.stderr.on('data', chunk => { stderr += chunk })
+    child.on('error', reject)
+    child.on('close', code => { resolve({ code: code ?? 1, stdout, stderr }) })
+  })
+}
+
+/**
+ * Remove the token from text that may reach the browser.
+ * @param text - command output.
+ * @param token - access token.
+ * @returns text with every occurrence replaced.
+ */
+export function scrubToken(text, token) {
+  if (token === undefined || token === '') return text
+  return String(text).split(token).join('[redacted]')
+}
+
+/**
+ * Ask the GitHub CLI for the token it already holds.
+ *
+ * Nothing is stored by this plugin: when `gh` is signed out, the feature says
+ * so instead of collecting a credential of its own.
+ * @param run - command runner, injected by tests.
+ * @returns the token, or undefined when `gh` is missing or signed out.
+ */
+export async function ghToken(run = runCommand) {
+  let answer
+  try {
+    answer = await run('gh', ['auth', 'token'])
+  } catch {
+    return undefined
+  }
+  if (answer.code !== 0) return undefined
+  const token = answer.stdout.trim()
+  return token === '' ? undefined : token
+}
+
+/**
+ * Read the login that owns a token.
+ * @param token - GitHub access token.
+ * @param fetchImpl - HTTP implementation.
+ * @returns the login name.
+ */
+export async function fetchLogin(token, fetchImpl = fetch) {
+  const response = await fetchImpl('https://api.github.com/user', { headers: githubHeaders(token) })
+  if (!response.ok) throw new Error(`GitHub sign-in check failed (${String(response.status)})`)
+  const body = await response.json()
+  const login = body?.login
+  if (typeof login !== 'string' || login === '') throw new Error('GitHub did not return a login')
+  return login
+}
+
+/**
+ * List repositories the token can clone, most recently updated first.
+ * @param token - GitHub access token.
+ * @param fetchImpl - HTTP implementation.
+ * @param pages - most pages of 100 to read.
+ * @returns repository rows in list order.
+ */
+export async function fetchRepos(token, fetchImpl = fetch, pages = 3) {
+  const repos = []
+  let url = 'https://api.github.com/user/repos?per_page=100&sort=updated&affiliation=owner,collaborator,organization_member'
+  for (let page = 0; page < pages && url !== undefined; page += 1) {
+    const response = await fetchImpl(url, { headers: githubHeaders(token) })
+    if (!response.ok) throw new Error(`GitHub repository list failed (${String(response.status)})`)
+    const body = await response.json()
+    if (!Array.isArray(body)) throw new Error('GitHub repository list was not an array')
+    for (const item of body) {
+      const row = readRepo(item)
+      if (row !== undefined) repos.push(row)
+    }
+    url = nextLink(response.headers.get('link'))
+  }
+  return repos
+}
+
+function githubHeaders(token) {
+  return {
+    accept: 'application/vnd.github+json',
+    authorization: `Bearer ${token}`,
+    'user-agent': 'aryacode-polish',
+  }
+}
+
+function readRepo(value) {
+  if (value === null || typeof value !== 'object') return undefined
+  const name = value.name
+  const owner = value.owner !== null && typeof value.owner === 'object' ? value.owner.login : undefined
+  if (typeof name !== 'string' || typeof owner !== 'string') return undefined
+  return {
+    owner,
+    name,
+    fullName: typeof value.full_name === 'string' ? value.full_name : `${owner}/${name}`,
+    isPrivate: value.private === true,
+    isFork: value.fork === true,
+    description: typeof value.description === 'string' ? value.description : '',
+    updatedAt: typeof value.updated_at === 'string' ? value.updated_at : '',
+    defaultBranch: typeof value.default_branch === 'string' ? value.default_branch : '',
+  }
+}
+
+function nextLink(header) {
+  if (typeof header !== 'string' || header === '') return undefined
+  for (const part of header.split(',')) {
+    const match = /<([^>]+)>;\s*rel="next"/.exec(part)
+    if (match?.[1] !== undefined) return match[1]
+  }
+  return undefined
+}
+
+async function directoryExists(path) {
+  try {
+    return (await stat(path)).isDirectory()
+  } catch {
+    return false
+  }
+}
+
+async function existingRealpath(path) {
+  try {
+    return await realpath(path)
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Clone a repository, or reuse a directory whose origin is already that repo.
+ *
+ * The token travels in git's environment as an http header, never in the
+ * remote URL and never on the command line, so it cannot leak through `ps` or
+ * a stored remote.
+ * @param owner - repository owner.
+ * @param name - repository name.
+ * @param token - GitHub access token.
+ * @param options - command runner, home directory and optional progress sink.
+ * @returns destination path and whether an existing checkout was kept.
+ */
+export async function cloneRepo(owner, name, token, options = {}) {
+  const run = options.run ?? runCommand
+  const path = cloneDestination(owner, name, options.home)
+  const progress = options.progress ?? (() => {})
+  if (await directoryExists(path)) {
+    const origin = await run('git', ['remote', 'get-url', 'origin'], { cwd: path })
+    if (origin.code === 0 && sameOrigin(origin.stdout, owner, name)) {
+      progress(`Reusing the existing checkout at ${path}`)
+      return { path, reused: true }
+    }
+    throw new Error(`${path} already exists and is not ${owner}/${name}`)
+  }
+  await mkdir(dirname(path), { recursive: true })
+  progress(`Cloning ${owner}/${name} into ${path}`)
+  // GitHub's git server rejects a bearer token, so it is presented as basic auth
+  // through an extra http header in git's own environment.
+  const header = `Authorization: Basic ${Buffer.from(`x-access-token:${token}`).toString('base64')}`
+  const cloned = await run(
+    'git',
+    ['-c', 'credential.helper=', 'clone', '--progress', '--', `https://github.com/${owner}/${name}.git`, path],
+    {
+      env: {
+        GIT_CONFIG_COUNT: '1',
+        GIT_CONFIG_KEY_0: 'http.extraHeader',
+        GIT_CONFIG_VALUE_0: header,
+      },
+    },
+  )
+  if (cloned.code !== 0) {
+    throw new Error(scrubToken(cloned.stderr || cloned.stdout || 'git clone failed', token))
+  }
+  return { path, reused: false }
+}
+
+/**
+ * Answer one browser request.
+ * @param body - parsed request body.
+ * @param deps - injected GitHub and git implementations.
+ * @returns the JSON value the browser half renders.
+ */
+export async function handleRequest(body, deps = {}) {
+  const action = body?.action
+  const token = await (deps.token ?? ghToken)()
+  if (action === 'status') {
+    if (token === undefined) {
+      return {
+        ok: true,
+        value: { signedIn: false, login: '', root: cloneRoot(deps.home), reason: 'The GitHub CLI is missing or not signed in: run `gh auth login` in a terminal.' },
+      }
+    }
+    const login = await (deps.login ?? fetchLogin)(token)
+    return { ok: true, value: { signedIn: true, login, root: cloneRoot(deps.home), reason: '' } }
+  }
+  if (token === undefined) {
+    return { ok: false, error: 'Sign in with the GitHub CLI first: run `gh auth login` in a terminal, then try again.' }
+  }
+  if (action === 'repos') {
+    const repos = await (deps.repos ?? fetchRepos)(token)
+    const marked = []
+    for (const repo of repos) {
+      const real = await existingRealpath(cloneDestination(repo.owner, repo.name, deps.home))
+      marked.push({ ...repo, cloned: real !== undefined })
+    }
+    return { ok: true, value: { root: cloneRoot(deps.home), repos: marked } }
+  }
+  if (action === 'clone') {
+    const owner = assertSegment(body.owner)
+    const name = assertSegment(body.name)
+    const result = await (deps.clone ?? cloneRepo)(owner, name, token, { home: deps.home })
+    return { ok: true, value: { path: result.path, reused: result.reused } }
+  }
+  return { ok: false, error: `unknown GitHub action: ${String(action)}` }
+}
+
+/**
+ * JSON response helper.
+ * @param value - payload to serialize.
+ * @param status - HTTP status.
+ * @returns a JSON response.
+ */
+export function json(value, status = 200) {
+  return new Response(JSON.stringify(value), {
+    status,
+    headers: { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' },
+  })
+}
+
+/** Mount the route on a context that provides the `connection` service. */
+export const githubFeature = {
+  name: 'polish-github',
+  inject: ['connection'],
+  apply(ctx, config = {}) {
+    ctx.effect(() => ctx.connection.fetch.register({
+      path: GITHUB_ROUTE,
+      // Without a method list the platform would only route GET, which is why the
+      // browser's POST would fall through to the static handler as a 404.
+      methods: ['POST'],
+      requestBody: 'buffered',
+      fetch: async (request) => {
+        if (request.method !== 'POST') return json({ ok: false, error: 'POST only' }, 405)
+        let body
+        try {
+          body = await request.json()
+        } catch {
+          return json({ ok: false, error: 'body must be JSON' }, 400)
+        }
+        try {
+          const deps = {
+            home: typeof config.home === 'string' && config.home !== '' ? config.home : undefined,
+          }
+          return json(await handleRequest(body, deps))
+        } catch (error) {
+          const message = error instanceof Error ? error.message : 'GitHub request failed'
+          return json({ ok: false, error: message })
+        }
+      },
+    }))
+  },
+}
+
+/**
+ * Register one child fiber carrying the GitHub route when a profile mounts the
+ * feature. Kept separate from the switch so turning the switch off removes the
+ * route together with every other surface.
+ * @param ctx - the row's context.
+ * @returns the mounted fiber.
+ */
+export function mountGithub(ctx, config = {}) {
+  return ctx.plugin({ ...githubFeature, config })
+}

package/entries/registry.js

@@ -24,6 +24,7 @@
  */
 
 import { mountCost } from './cost.js'
+import { mountGithub } from './github.js'
 
 /**
  * Every feature this bundle ships. Spelling corrections are investigated and
@@ -46,6 +47,19 @@ export const features = [
     description: 'Show the remaining account balance in the sidebar foot, above the account row.',
     defaultOn: true,
   },
+  {
+    id: 'openWorkspaceFolder',
+    label: 'Open workspace folder',
+    description: 'Add an "Open workspace folder" row to a Session\u2019s menu that opens its workspace in the file browser.',
+    defaultOn: true,
+  },
+  {
+    id: 'githubWorkspace',
+    label: 'Add a workspace from GitHub',
+    description: 'Sign in with the GitHub CLI, browse your repositories, and clone one as a workspace.',
+    defaultOn: true,
+    mount: mountGithub,
+  },
 ]
 
 /**