@aryacode/dsh-aryacode-polish 0.4.4 → 0.6.0

package/client/switches.json

@@ -16,7 +16,19 @@
     {
       "key": "openWorkspaceFolder",
       "label": "Open workspace folder",
-      "description": "Add an \u201cOpen workspace folder\u201d row to a Session\u2019s menu that opens its workspace in the file browser.",
+      "description": "Add an “Open workspace folder” row to a Session’s menu that opens its workspace in the file browser.",
+      "defaultOn": true
+    },
+    {
+      "key": "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
+    },
+    {
+      "key": "workspaceSources",
+      "label": "Add a workspace from this PC or GitHub",
+      "description": "Put an On this PC / GitHub repository source menu behind the Workspaces + button.",
       "defaultOn": true
     }
   ]

package/docs/github-workspaces.md

@@ -0,0 +1,81 @@
+# 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`.
+
+## How the entry point works
+
+The "+" menu's **Add workspace…** entry only appears when something occupies
+`sidebar.workspaces.directoryFlow`, and that slot is `kind: 'single'` — whoever
+takes it stands in for the folder picker. This bundle takes it and offers the
+two sources the owner asked for:
+
+- **On this PC** — a folder browser driven by this bundle's own route
+  (`api/polish.folders`, actions `roots` and `ls`): roots, a `..` row for going
+  back, directories only, hidden and system entries filtered out, and **Use this
+  folder** hands the current path to the flow's `onPicked`.
+- **GitHub repository…** — the dialog described above. It opens on behalf of the
+  flow, so a finished clone hands its path back through the flow's `onPicked`,
+  and the Shell creates the workspace exactly as it does for a picked folder.
+
+### Why the browser does not borrow the Host's chooser
+
+A composed directory picker serves exactly one capability: `browse` answers
+`list` and `createDirectory`, `native` answers `pick`. The web profile composes
+the picker whose chooser cannot open there, so `directoryPicker.pick()` waits on
+a dialog that never appears — the first build of this flow did exactly that and
+the row spun forever. Owning the listing keeps one behaviour in the app and in
+the browser, needs no capability guess, and does not break when a profile mounts
+a different picker.
+
+The tray of the foot keeps the sign-in state (`GitHub · <login>`, or
+`GitHub · signed out`) next to the balance, so the account is visible without
+opening a dialog; clicking it opens the repository dialog directly.
+
+## 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

@@ -55,6 +55,12 @@ If the harness ever declares a workspace-scoped menu slot, this feature should m
 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`.

package/entries/folders.js

@@ -0,0 +1,115 @@
+/**
+ * The folder list behind "On this PC".
+ *
+ * Why this exists at all: the add-a-workspace flow is driven by the
+ * `sidebar.workspaces.directoryFlow` slot, whose single occupant is a directory
+ * picker. A picker serves exactly one capability — `browse` (`list`,
+ * `createDirectory`) or `native` (`pick`) — and the browser build composes the
+ * one without a chooser to show, so `pick` there waits for a dialog that never
+ * opens. Owning the listing instead of borrowing it keeps the row behaving the
+ * same in the app and in the browser, and keeps the plugin free of a dependency
+ * on which picker a profile happens to mount.
+ *
+ * The route is the same documented shape the GitHub half uses: a registered
+ * `connection.fetch` path, answering JSON, with the browser addressing the
+ * document-relative form.
+ */
+import { promises as fs } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { json } from './github.js'
+
+/** Absolute path the Host registers; the browser uses {@link FOLDERS_ROUTE}. */
+export const FOLDERS_PATH = '/api/polish.folders'
+
+/** Document-relative form the bundle calls with `fetch`. */
+export const FOLDERS_ROUTE = FOLDERS_PATH.slice(1)
+
+/**
+ * Places a folder browser can start from.
+ *
+ * @returns labelled roots, the profile's home first.
+ */
+export function folderRoots(home = homedir()) {
+  const roots = [{ label: 'Home', path: home }]
+  const drive = process.env.SystemDrive ?? 'C:'
+  if (drive !== '') roots.push({ label: `${drive}\\`, path: `${drive}\\` })
+  return roots
+}
+
+/**
+ * List the subdirectories of one directory.
+ *
+ * @param input - a directory path; the client passes what the previous listing
+ *   returned, and never a path it composed itself.
+ * @returns the resolved path, its parent (null at a drive root) and the child
+ *   folders sorted by name, hidden entries excluded.
+ */
+export async function listFolders(input) {
+  if (typeof input !== 'string' || input === '') {
+    throw new Error('a folder path is required')
+  }
+  const path = resolve(input)
+  const entries = []
+  for (const entry of await fs.readdir(path, { withFileTypes: true })) {
+    if (entry.name.startsWith('.') || entry.name.startsWith('$')) continue
+    if (entry.isDirectory() === false) continue
+    entries.push({ name: entry.name, path: join(path, entry.name) })
+  }
+  entries.sort((left, right) => left.name.localeCompare(right.name, undefined, { sensitivity: 'base' }))
+  const parent = dirname(path)
+  return { path, parent: parent === path ? null : parent, entries }
+}
+
+/**
+ * Answer one request from the browser.
+ *
+ * @param body - `{ action: 'roots' }` or `{ action: 'ls', path }`.
+ * @returns a Response with a JSON body.
+ */
+export async function handleFolders(body) {
+  const action = body?.action
+  if (action === 'roots') return json({ roots: folderRoots() })
+  if (action === 'ls') {
+    try {
+      return json(await listFolders(body.path))
+    } catch (error) {
+      return json({ error: error instanceof Error ? error.message : 'cannot list that folder' }, 400)
+    }
+  }
+  return json({ error: `unknown action ${String(action)}` }, 400)
+}
+
+/** The host half mounted by the `workspaceSources` feature. */
+export const foldersFeature = {
+  name: 'polish-folders',
+  inject: ['connection'],
+  apply(ctx) {
+    ctx.effect(() => ctx.connection.fetch.register({
+      path: FOLDERS_PATH,
+      methods: ['POST'],
+      requestBody: 'buffered',
+      fetch: async request => {
+        if (request.method !== 'POST') return json({ error: 'POST required' }, 405)
+        let body
+        try {
+          body = await request.json()
+        } catch {
+          return json({ error: 'a JSON body is required' }, 400)
+        }
+        return handleFolders(body)
+      },
+    }))
+  },
+}
+
+/**
+ * Mount the folder route for one configuration.
+ *
+ * @param ctx - the row's context.
+ * @param config - the row's resolved configuration accessor.
+ * @returns the mounted plugin fiber.
+ */
+export function mountFolders(ctx, config) {
+  return ctx.plugin({ ...foldersFeature, config })
+}

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,8 @@
  */
 
 import { mountCost } from './cost.js'
+import { mountFolders } from './folders.js'
+import { mountGithub } from './github.js'
 
 /**
  * Every feature this bundle ships. Spelling corrections are investigated and
@@ -52,6 +54,20 @@ export const features = [
     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,
+  },
+  {
+    id: 'workspaceSources',
+    label: 'Add a workspace from this PC or GitHub',
+    description: 'Put an "On this PC" / "GitHub repository" source menu behind the Workspaces + button.',
+    defaultOn: true,
+    mount: mountFolders,
+  },
 ]
 
 /**