dsh-plugin-syncup 0.0.0-stage → 4.1.0

package/lib/github.js

@@ -0,0 +1,305 @@
+import { readFileSync } from 'node:fs'
+import { emptyManifest, normalizeManifest } from './manifest.js'
+import { expandHome } from './spec.js'
+
+const USER_AGENT = 'dsh-plugin-syncup/2.2.0'
+const MAX_MANIFEST_BYTES = 1_000_000
+
+export class GitHubError extends Error {
+  constructor(message, { code = 'github-error', status = undefined, retryable = false, body = undefined } = {}) {
+    super(message)
+    this.name = 'GitHubError'
+    this.code = code
+    this.status = status
+    this.retryable = retryable
+    this.body = body
+  }
+}
+
+export function resolveToken({ token = '', tokenEnv = 'GITHUB_TOKEN', tokenFile = '', env = process.env } = {}) {
+  if (typeof token === 'string' && token.trim() !== '') {
+    return { token: token.trim(), source: 'config' }
+  }
+  if (typeof tokenEnv === 'string' && tokenEnv.trim() !== '') {
+    const value = env[tokenEnv.trim()]
+    if (typeof value === 'string' && value.trim() !== '') {
+      return { token: value.trim(), source: `env:${tokenEnv.trim()}` }
+    }
+  }
+  const file = expandHome(tokenFile)
+  if (file !== '') {
+    try {
+      const value = readFileSync(file, 'utf8').trim()
+      if (value !== '') return { token: value, source: 'file' }
+    } catch {
+      return { token: '', source: null }
+    }
+  }
+  return { token: '', source: null }
+}
+
+function parseApiBase(value) {
+  const fallback = 'https://api.github.com'
+  if (typeof value !== 'string' || value.trim() === '') return fallback
+  let url
+  try {
+    url = new URL(value.trim())
+  } catch {
+    return fallback
+  }
+  url.search = ''
+  url.hash = ''
+  return url.toString().replace(/\/+$/, '')
+}
+
+function errorMessageFromBody(body, status) {
+  if (typeof body === 'string' && body.trim() !== '') return body.trim().slice(0, 500)
+  if (body !== null && typeof body === 'object' && typeof body.message === 'string') {
+    const details = Array.isArray(body.errors)
+      ? body.errors
+          .map((item) => (typeof item === 'string' ? item : item?.message ?? item?.code ?? ''))
+          .filter((item) => typeof item === 'string' && item !== '')
+      : []
+    const suffix = details.length === 0 ? '' : ` (${details.join('; ')})`
+    return `${body.message}${suffix}`.slice(0, 500)
+  }
+  return `GitHub API request failed with status ${status}`
+}
+
+function gistVersion(gist) {
+  if (gist !== null && typeof gist === 'object' && Array.isArray(gist.history)) {
+    const version = gist.history[0]?.version
+    if (typeof version === 'string' && version !== '') return version
+  }
+  return typeof gist?.updated_at === 'string' ? gist.updated_at : null
+}
+
+function gistSummary(gist) {
+  return {
+    gistId: typeof gist?.id === 'string' ? gist.id : null,
+    htmlUrl: typeof gist?.html_url === 'string' ? gist.html_url : null,
+    description: typeof gist?.description === 'string' ? gist.description : null,
+    updatedAt: typeof gist?.updated_at === 'string' ? gist.updated_at : null,
+    version: gistVersion(gist),
+    public: gist?.public === true,
+  }
+}
+
+function gistFileName(value) {
+  return typeof value === 'string' && value.trim() !== '' ? value.trim() : 'dsh-plugins.json'
+}
+
+export function createGitHubClient({
+  apiBaseUrl = 'https://api.github.com',
+  token = '',
+  timeoutMs = 20_000,
+  fetchImpl = globalThis.fetch,
+} = {}) {
+  if (typeof fetchImpl !== 'function') throw new GitHubError('fetch is unavailable in this Host', { code: 'no-fetch' })
+  const base = parseApiBase(apiBaseUrl)
+
+  async function requestUrl(url, { method = 'GET', body, headers = {}, allow404 = false, extraSignal } = {}) {
+    const requestHeaders = {
+      accept: 'application/vnd.github+json',
+      'x-github-api-version': '2022-11-28',
+      'user-agent': USER_AGENT,
+      ...headers,
+    }
+    if (token !== '') requestHeaders.authorization = `Bearer ${token}`
+    if (body !== undefined) requestHeaders['content-type'] = 'application/json'
+    const signals = [AbortSignal.timeout(timeoutMs)]
+    for (const candidate of [extraSignal]) {
+      if (candidate !== undefined) signals.push(candidate)
+    }
+    const combined = signals.length === 1 ? signals[0] : AbortSignal.any(signals)
+    let response
+    try {
+      response = await fetchImpl(url, {
+        method,
+        headers: requestHeaders,
+        body: body === undefined ? undefined : JSON.stringify(body),
+        signal: combined,
+      })
+    } catch (error) {
+      if (combined.aborted) {
+        throw new GitHubError('GitHub request was aborted or timed out', { code: 'timeout', retryable: true })
+      }
+      throw new GitHubError(`GitHub request failed: ${error instanceof Error ? error.message : String(error)}`, {
+        code: 'network',
+        retryable: true,
+      })
+    }
+    const raw = await response.text()
+    let parsed = null
+    if (raw.trim() !== '') {
+      try {
+        parsed = JSON.parse(raw)
+      } catch {
+        parsed = raw
+      }
+    }
+    if (response.ok) return { status: response.status, body: parsed, headers: response.headers }
+    if (response.status === 404 && allow404) return null
+    if (response.status === 409 || response.status === 412) {
+      throw new GitHubError(errorMessageFromBody(parsed, response.status), {
+        code: 'conflict',
+        status: response.status,
+        retryable: true,
+        body: parsed,
+      })
+    }
+    const retryable = response.status === 429 || response.status >= 500
+    const code = response.status === 401 || response.status === 403
+      ? 'auth'
+      : response.status === 404
+        ? 'not-found'
+        : retryable
+          ? 'server'
+          : 'github-error'
+    throw new GitHubError(errorMessageFromBody(parsed, response.status), {
+      code,
+      status: response.status,
+      retryable,
+      body: parsed,
+    })
+  }
+
+  async function readGist(gistId, fileName = 'dsh-plugins.json', { extraSignal } = {}) {
+    if (typeof gistId !== 'string' || gistId === '') throw new GitHubError('A Gist id is required', { code: 'invalid-gist' })
+    const name = gistFileName(fileName)
+    const response = await requestUrl(`${base}/gists/${encodeURIComponent(gistId)}`, {
+      allow404: true,
+      extraSignal,
+    })
+    if (response === null) {
+      throw new GitHubError(`Gist ${gistId} was not found or is not accessible with this token`, { code: 'not-found' })
+    }
+    const gist = response.body
+    const summary = gistSummary(gist)
+    const file = gist !== null && typeof gist === 'object' && gist.files !== null && typeof gist.files === 'object'
+      ? gist.files[name]
+      : undefined
+    if (file === undefined || file === null) {
+      return {
+        ...summary,
+        exists: false,
+        fileName: name,
+        manifest: emptyManifest(),
+        etag: response.headers.get('etag'),
+      }
+    }
+    let text = typeof file.content === 'string' ? file.content : ''
+    if (file.truncated === true || (text === '' && typeof file.raw_url === 'string')) {
+      if (typeof file.raw_url !== 'string' || file.raw_url === '') {
+        throw new GitHubError(`Gist file ${name} is truncated and has no raw URL`, { code: 'invalid-response' })
+      }
+      const raw = await requestUrl(file.raw_url, {
+        headers: { accept: 'text/plain' },
+        extraSignal,
+      })
+      text = typeof raw.body === 'string'
+        ? raw.body
+        : raw.body === null || raw.body === undefined ? '' : JSON.stringify(raw.body)
+    }
+    if (Buffer.byteLength(text, 'utf8') > MAX_MANIFEST_BYTES) {
+      throw new GitHubError(`Gist manifest ${name} is larger than 1 MB`, { code: 'manifest-too-large' })
+    }
+    let parsed
+    try {
+      parsed = JSON.parse(text)
+    } catch {
+      throw new GitHubError(`Gist file ${name} is not valid JSON`, { code: 'invalid-manifest' })
+    }
+    const manifest = normalizeManifest(parsed, { source: `gist ${gistId}/${name}`, requireShape: true })
+    return {
+      ...summary,
+      exists: true,
+      fileName: name,
+      manifest,
+      etag: response.headers.get('etag'),
+    }
+  }
+
+  async function listGists({ extraSignal } = {}) {
+    const response = await requestUrl(`${base}/gists?per_page=100`, { extraSignal })
+    if (!Array.isArray(response.body)) {
+      throw new GitHubError('GitHub did not return a Gist list', { code: 'invalid-response' })
+    }
+    return response.body.map(gistSummary)
+  }
+
+  async function createGist({ description = 'DSH plugin inventory', fileName = 'dsh-plugins.json', manifest, extraSignal } = {}) {
+    if (token === '') {
+      throw new GitHubError('A GitHub token is required to create a Gist', { code: 'no-token' })
+    }
+    const name = gistFileName(fileName)
+    const text = `${JSON.stringify(manifest, null, 2)}\n`
+    if (Buffer.byteLength(text, 'utf8') > MAX_MANIFEST_BYTES) {
+      throw new GitHubError('Manifest is larger than 1 MB', { code: 'manifest-too-large' })
+    }
+    const response = await requestUrl(`${base}/gists`, {
+      method: 'POST',
+      body: {
+        description,
+        public: false,
+        files: { [name]: { content: text } },
+      },
+      extraSignal,
+    })
+    return { ...gistSummary(response.body), fileName: name }
+  }
+
+  /**
+   * Update a Gist's manifest file.
+   *
+   * GitHub rejects conditional headers on this endpoint ("Conditional request
+   * headers are not allowed in unsafe requests unless supported by the
+   * endpoint"), so conflict detection uses the read-then-merge retry in the
+   * caller instead of If-Match. `expectedVersion` is only used to detect that
+   * someone else changed the Gist between the caller's read and this write.
+   */
+  async function updateGist(gistId, {
+    description = 'DSH plugin inventory',
+    fileName = 'dsh-plugins.json',
+    manifest,
+    expectedVersion = null,
+    extraSignal,
+  } = {}) {
+    if (token === '') {
+      throw new GitHubError('A GitHub token is required to update a Gist', { code: 'no-token' })
+    }
+    const name = gistFileName(fileName)
+    const text = `${JSON.stringify(manifest, null, 2)}\n`
+    if (Buffer.byteLength(text, 'utf8') > MAX_MANIFEST_BYTES) {
+      throw new GitHubError('Manifest is larger than 1 MB', { code: 'manifest-too-large' })
+    }
+    if (expectedVersion !== null) {
+      const current = await requestUrl(`${base}/gists/${encodeURIComponent(gistId)}`, { extraSignal })
+      const currentVersion = gistVersion(current.body)
+      if (currentVersion !== null && currentVersion !== expectedVersion) {
+        throw new GitHubError('The Gist changed after it was read; retry the update', {
+          code: 'conflict',
+          status: 412,
+          retryable: true,
+        })
+      }
+    }
+    const response = await requestUrl(`${base}/gists/${encodeURIComponent(gistId)}`, {
+      method: 'PATCH',
+      body: {
+        description,
+        files: { [name]: { content: text } },
+      },
+      extraSignal,
+    })
+    return { ...gistSummary(response.body), fileName: name }
+  }
+
+  return {
+    apiBaseUrl: base,
+    readGist,
+    listGists,
+    createGist,
+    updateGist,
+  }
+}

package/lib/http.js

@@ -0,0 +1,285 @@
+import {
+  clearCredential,
+  ConfigError,
+  describeCredential,
+  readConfigSnapshot,
+  setCredential,
+  writeConfigValues,
+} from './config.js'
+
+const API_PREFIX = '/dsh-plugin-syncup/api/v2'
+const MAX_BODY_BYTES = 64 * 1024
+
+function sendJson(response, status, payload) {
+  const body = `${JSON.stringify(payload)}\n`
+  response.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store',
+    'content-length': Buffer.byteLength(body),
+  })
+  response.end(body)
+}
+
+function sendError(response, status, code, message) {
+  sendJson(response, status, { ok: false, error: { code, message } })
+}
+
+function sameOrigin(request) {
+  const origin = request.headers.origin
+  if (typeof origin !== 'string' || origin === '') return true
+  try {
+    return new URL(origin).host === request.headers.host
+  } catch {
+    return false
+  }
+}
+
+async function readJson(request) {
+  const length = Number(request.headers['content-length'] ?? 0)
+  if (Number.isFinite(length) && length > MAX_BODY_BYTES) {
+    const error = new Error('Request body is too large')
+    error.status = 413
+    throw error
+  }
+  let total = 0
+  const chunks = []
+  for await (const chunk of request) {
+    total += chunk.length
+    if (total > MAX_BODY_BYTES) {
+      const error = new Error('Request body is too large')
+      error.status = 413
+      throw error
+    }
+    chunks.push(chunk)
+  }
+  if (total === 0) return {}
+  try {
+    const parsed = JSON.parse(Buffer.concat(chunks).toString('utf8'))
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      throw new Error('JSON body must be an object')
+    }
+    return parsed
+  } catch (error) {
+    const failure = new Error(`Invalid JSON body: ${error instanceof Error ? error.message : String(error)}`)
+    failure.status = 400
+    throw failure
+  }
+}
+
+function isRecord(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function methodGuard(request, response, allowed) {
+  if (allowed.includes(request.method)) return true
+  response.writeHead(405, { allow: allowed.join(', ') })
+  response.end()
+  return false
+}
+
+export function registerApiRoutes({ ctx, runtime, config }) {
+  const routes = [
+    {
+      name: 'status',
+      methods: ['GET'],
+      path: `${API_PREFIX}/status`,
+      handle: async (_request, response) => {
+        const status = await runtime.status()
+        const credential = await describeCredential(ctx)
+        if (credential.available) {
+          status.token = {
+            configured: credential.configured,
+            source: credential.source,
+            writable: credential.writable,
+          }
+        }
+        const configSnapshot = readConfigSnapshot(ctx, config)
+        sendJson(response, 200, {
+          ...status,
+          configSnapshot,
+        })
+      },
+    },
+    {
+      name: 'config',
+      methods: ['GET', 'POST'],
+      path: `${API_PREFIX}/config`,
+      handle: async (request, response) => {
+        if (request.method === 'GET') {
+          sendJson(response, 200, {
+            ok: true,
+            config: readConfigSnapshot(ctx, config),
+            credential: await describeCredential(ctx),
+          })
+          return
+        }
+        const body = await readJson(request)
+        if (!isRecord(body.values)) {
+          sendError(response, 400, 'invalid-request', 'values must be an object')
+          return
+        }
+        if (body.clearToken === true) {
+          await clearCredential(ctx)
+        } else if (typeof body.token === 'string' && body.token.trim() !== '') {
+          await setCredential(ctx, body.token)
+        }
+        const values = await writeConfigValues(ctx, body.values, config)
+        sendJson(response, 200, {
+          ok: true,
+          values,
+          credential: await describeCredential(ctx),
+        })
+      },
+    },
+    {
+      name: 'jobs',
+      methods: ['GET'],
+      path: `${API_PREFIX}/jobs`,
+      handle: async (request, response) => {
+        const url = new URL(request.url ?? '/', 'http://127.0.0.1')
+        const jobId = url.searchParams.get('id')
+        if (typeof jobId === 'string' && jobId !== '') {
+          const job = runtime.job(jobId)
+          if (job === null) {
+            sendError(response, 404, 'job-not-found', `No job with id ${jobId}`)
+            return
+          }
+          sendJson(response, 200, { ok: true, job })
+          return
+        }
+        const kind = url.searchParams.get('kind')
+        sendJson(response, 200, {
+          ok: true,
+          latest: runtime.latestJob(kind === null ? undefined : kind),
+          jobs: runtime.jobs(kind === null ? undefined : kind),
+        })
+      },
+    },
+    {
+      name: 'latest',
+      methods: ['GET', 'POST'],
+      path: `${API_PREFIX}/latest`,
+      handle: async (request, response) => {
+        if (request.method === 'GET') {
+          // `cached=1` restores the last result without re-querying the registries,
+          // so a page that remounts mid-work does not start a second check.
+          const url = new URL(request.url ?? '/', 'http://127.0.0.1')
+          if (url.searchParams.get('cached') === '1') {
+            const cached = runtime.cachedLatest()
+            sendJson(response, 200, cached === null
+              ? { ok: true, cached: false, entries: [], counts: { entries: 0, outdated: 0, current: 0, unsupported: 0, failed: 0 } }
+              : { ok: true, cached: true, ...cached })
+            return
+          }
+          const result = await runtime.checkLatest()
+          sendJson(response, 200, result)
+          return
+        }
+        const body = await readJson(request)
+        if (!Array.isArray(body.names)) {
+          sendError(response, 400, 'invalid-request', 'names must be an array of bundle names')
+          return
+        }
+        const result = await runtime.applyLatest(body.names, {
+          channel: typeof body.channel === 'string' ? body.channel : null,
+          channels: isRecord(body.channels) ? body.channels : {},
+        })
+        sendJson(response, 200, result)
+      },
+    },
+    {
+      name: 'preview',
+      methods: ['POST'],
+      path: `${API_PREFIX}/preview`,
+      handle: async (_request, response) => {
+        const preview = await runtime.preview()
+        sendJson(response, 200, preview)
+      },
+    },
+    {
+      name: 'apply',
+      methods: ['POST'],
+      path: `${API_PREFIX}/apply`,
+      handle: async (request, response) => {
+        const body = await readJson(request)
+        if (typeof body.previewId !== 'string' || body.previewId === '') {
+          sendError(response, 400, 'invalid-request', 'previewId is required')
+          return
+        }
+        if (!isRecord(body.selections)) {
+          sendError(response, 400, 'invalid-request', 'selections must be an object')
+          return
+        }
+        const result = await runtime.apply(body.previewId, body.selections)
+        sendJson(response, 200, result)
+      },
+    },
+    {
+      name: 'push',
+      methods: ['POST'],
+      path: `${API_PREFIX}/push`,
+      handle: async (request, response) => {
+        const body = await readJson(request)
+        if (body.confirm !== true) {
+          sendError(response, 400, 'confirm-required', 'Set confirm=true to update the remote manifest')
+          return
+        }
+        const result = await runtime.push({
+          planId: typeof body.planId === 'string' && body.planId !== '' ? body.planId : null,
+          selections: isRecord(body.selections) ? body.selections : {},
+        })
+        sendJson(response, 200, result)
+      },
+    },
+    {
+      name: 'plan-push',
+      methods: ['POST'],
+      path: `${API_PREFIX}/push/plan`,
+      handle: async (_request, response) => {
+        const result = await runtime.planPush()
+        sendJson(response, 200, result)
+      },
+    },
+  ]
+
+  const mount = (hostCtx) => {
+    hostCtx.effect(() => {
+      const disposers = []
+      for (const route of routes) {
+        disposers.push(hostCtx.webServer.register({
+          kind: 'exact',
+          path: route.path,
+          handler: async (request, response) => {
+            if (!sameOrigin(request)) {
+              sendError(response, 403, 'cross-origin', 'Cross-origin requests are not allowed')
+              return
+            }
+            if (!methodGuard(request, response, route.methods)) return
+            try {
+              await route.handle(request, response)
+            } catch (error) {
+              if (error instanceof ConfigError) {
+                sendError(response, 400, error.code, error.message)
+                return
+              }
+              const status = typeof error?.status === 'number' ? error.status : 500
+              const code = typeof error?.code === 'string' ? error.code : 'operation-failed'
+              const message = error instanceof Error ? error.message : String(error)
+              sendError(response, status, code, message)
+            }
+          },
+        }))
+      }
+      return () => {
+        for (const dispose of disposers) dispose()
+      }
+    }, 'plugin-sync: API routes')
+  }
+
+  const existing = ctx.get('webServer')
+  if (existing !== undefined && existing !== null) {
+    mount({ webServer: existing, effect: ctx.effect.bind(ctx) })
+  } else {
+    ctx.inject(['webServer'], mount)
+  }
+}

package/lib/jobs.js

@@ -0,0 +1,107 @@
+import { randomUUID } from 'node:crypto'
+
+const MAX_JOBS = 10
+const MAX_LINES = 400
+
+function nowIso(now) {
+  return now().toISOString()
+}
+
+function clampText(value) {
+  const text = typeof value === 'string' ? value : String(value ?? '')
+  return text.length > 2000 ? `${text.slice(0, 2000)}…` : text
+}
+
+export function createJobStore({ now = () => new Date(), keep = MAX_JOBS } = {}) {
+  const jobs = new Map()
+
+  function trim() {
+    while (jobs.size > keep) {
+      const oldest = jobs.keys().next().value
+      if (oldest === undefined) return
+      jobs.delete(oldest)
+    }
+  }
+
+  function start(kind, meta = {}) {
+    const job = {
+      id: randomUUID(),
+      kind,
+      status: 'running',
+      startedAt: nowIso(now),
+      finishedAt: null,
+      progress: { done: 0, total: 0 },
+      lines: [],
+      result: null,
+      error: null,
+      ...meta,
+    }
+    jobs.set(job.id, job)
+    trim()
+    return job
+  }
+
+  function append(jobId, level, message) {
+    const job = jobs.get(jobId)
+    if (job === undefined) return
+    job.lines.push({ at: nowIso(now), level, message: clampText(message) })
+    if (job.lines.length > MAX_LINES) job.lines.splice(0, job.lines.length - MAX_LINES)
+  }
+
+  function progress(jobId, done, total) {
+    const job = jobs.get(jobId)
+    if (job === undefined) return
+    job.progress = { done, total }
+  }
+
+  function finish(jobId, { result = null, error = null } = {}) {
+    const job = jobs.get(jobId)
+    if (job === undefined) return null
+    job.status = error === null ? 'done' : 'failed'
+    job.finishedAt = nowIso(now)
+    job.result = result
+    job.error = error === null ? null : clampText(error)
+    if (job.progress.total > 0) job.progress = { ...job.progress, done: job.progress.total }
+    return snapshot(job)
+  }
+
+  function snapshot(job) {
+    if (job === undefined || job === null) return null
+    return {
+      id: job.id,
+      kind: job.kind,
+      status: job.status,
+      startedAt: job.startedAt,
+      finishedAt: job.finishedAt,
+      progress: job.progress,
+      lines: job.lines,
+      result: job.result,
+      error: job.error,
+      ...(job.previewId === undefined ? {} : { previewId: job.previewId }),
+    }
+  }
+
+  function get(jobId) {
+    return snapshot(jobs.get(jobId))
+  }
+
+  function latest(kind) {
+    let found = null
+    for (const job of jobs.values()) {
+      if (kind !== undefined && job.kind !== kind) continue
+      found = job
+    }
+    return snapshot(found)
+  }
+
+  function list(kind) {
+    const items = []
+    for (const job of jobs.values()) {
+      if (kind !== undefined && job.kind !== kind) continue
+      items.push(snapshot(job))
+    }
+    return items.slice(-keep).reverse()
+  }
+
+  return { start, append, progress, finish, get, latest, list }
+}