omakit 0.1.0

package/tools/marketplace/github.mjs

@@ -0,0 +1,206 @@
+// Read-only GitHub access. GET only, no mutation of any kind, and the
+// credential is borrowed, used for GET, and never written anywhere.
+//
+// Omakit is read-only against omacom/omarchy-plugin-marketplace at all times.
+// There is no code path in this repository that issues a POST, PATCH, PUT or
+// DELETE, and no code path that creates an issue, comment, label or pull
+// request. `omakit submit` prints a body for a person to post; it never posts.
+
+import { execFileSync } from "node:child_process"
+
+export class GitHubError extends Error {
+  constructor(code, message, status) {
+    super(message)
+    this.name = "GitHubError"
+    this.code = code
+    this.status = status
+  }
+}
+
+const USER_AGENT = "omakit-marketplace-submit (read-only; https://github.com/mtolhuys/omakit)"
+
+/**
+ * Where the read-only credential comes from, in order.
+ *
+ * `gh` is first among the things a person actually has. The audience for this
+ * tool is people who submit plugins to a GitHub-hosted marketplace by opening
+ * an issue; the overlap between them and people with `gh auth login` already
+ * done is most of them. Asking them instead to mint a personal access token,
+ * for a tool that only ever issues GET, is a bad trade: it is friction for the
+ * honest case and a new long-lived secret on disk for the dishonest one. And
+ * `gh` is the only source: it honours GH_TOKEN and GITHUB_TOKEN itself
+ * (measured: `gh auth token` prints an environment token straight back), so
+ * an agent with a token in its environment is covered through the same one
+ * call, and omakit reads no variable of its own.
+ *
+ * Borrowing `gh`'s credential means borrowing whatever scopes that login has,
+ * which is usually enough to write. This repository keeps that safe the only
+ * way worth trusting, which is structurally rather than by intention: there is
+ * exactly one `fetch` call site in the whole tool, it is in this file, its
+ * method is the literal "GET", and tests/unit/read-only.test.mjs fails the
+ * suite if a second one appears anywhere, if any file spawns `gh` with
+ * arguments other than the four below, or if a credential is ever written to
+ * disk.
+ */
+export const GH_ARGS = Object.freeze(["auth", "token", "--hostname", "github.com"])
+
+/** GitHub's unauthenticated REST allowance, per hour, per IP. */
+export const UNAUTHENTICATED_LIMIT = 60
+
+// Long enough for a cold `gh` on a slow disk, short enough that a broken `gh`
+// cannot hold up a command that does not need a credential at all.
+const GH_TIMEOUT_MS = 4000
+
+// A token shape, not a token: enough to tell a credential from `gh`'s own
+// "not logged in" chatter, and it is never logged either way.
+const TOKEN_SHAPE = /^[A-Za-z0-9_.-]{20,255}$/
+
+/** The credential `gh` holds for github.com, or null if there is not one. */
+export function ghCredential({ run = execFileSync } = {}) {
+  let printed
+  try {
+    printed = run("gh", [...GH_ARGS], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: GH_TIMEOUT_MS,
+    })
+  } catch {
+    // Not installed, not signed in, or too slow to wait for. All three mean the
+    // same thing here, and none of them is an error worth reporting: every
+    // command that needs a credential works without one, just rate-limited.
+    return null
+  }
+  const value = String(printed || "").trim()
+  return TOKEN_SHAPE.test(value) ? value : null
+}
+
+/**
+ * @param {{ gh?: () => string|null }} [options]
+ * @returns {{ value: string|null, source: "gh"|null, detail: string }}
+ */
+export function resolveCredential({ gh = ghCredential } = {}) {
+  const borrowed = gh()
+  if (borrowed) return { value: borrowed, source: "gh", detail: "read from your `gh` login" }
+  return {
+    value: null,
+    source: null,
+    detail: `no GitHub login found; GitHub allows ${UNAUTHENTICATED_LIMIT} unauthenticated requests an hour`,
+  }
+}
+
+let resolved = null
+
+/**
+ * The resolved credential, looked up once per process.
+ *
+ * Cached because resolving it may spawn `gh`, and `watch` asks for it on every
+ * request. `refresh` is for the two commands that report the answer to a person
+ * rather than use it.
+ */
+export function credential({ refresh = false } = {}) {
+  if (refresh || !resolved) resolved = resolveCredential()
+  return resolved
+}
+
+export function token() {
+  return credential().value
+}
+
+async function get(url, { accept = "application/vnd.github+json" } = {}) {
+  const headers = { accept, "user-agent": USER_AGENT }
+  const auth = token()
+  if (auth) headers.authorization = `Bearer ${auth}`
+  let response
+  try {
+    response = await fetch(url, { method: "GET", headers, redirect: "follow" })
+  } catch (error) {
+    // Node reports every transport failure as "fetch failed" with the real
+    // reason in `cause`. A person needs the reason, and the CLI keys its
+    // remedy on the code, so both are carried out of here.
+    const cause = error?.cause?.code || error?.cause?.message || error?.message || "fetch failed"
+    const { host, pathname } = new URL(url)
+    throw new GitHubError("network-unavailable", `${host} did not answer (${cause}) while reading ${pathname}`)
+  }
+  if (!response.ok) {
+    const remaining = response.headers.get("x-ratelimit-remaining")
+    const hint = response.status === 403 && remaining === "0"
+      ? (auth
+        ? " (GitHub rate limit exhausted even authenticated; it resets within the hour)"
+        : ` (GitHub rate limit exhausted at ${UNAUTHENTICATED_LIMIT} requests an hour; \`gh auth login\` raises it, and omakit reads that login read-only)`)
+      : ""
+    throw new GitHubError(
+      response.status === 404 ? "not-found" : "github-unavailable",
+      `GET ${url} returned ${response.status}${hint}`,
+      response.status,
+    )
+  }
+  return response
+}
+
+export async function getJson(url) {
+  return (await get(url)).json()
+}
+
+export async function getText(url, accept) {
+  return (await get(url, { accept })).text()
+}
+
+/** Parse a marketplace issue URL into its parts. */
+export function parseIssueUrl(value) {
+  const match = String(value || "").trim().match(
+    /^https:\/\/github\.com\/([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)\/issues\/(\d+)(?:[?#].*)?$/,
+  )
+  if (!match) throw new GitHubError("usage", `not a GitHub issue URL: ${value}`)
+  return { owner: match[1], repository: match[2], number: Number(match[3]) }
+}
+
+export async function issue(owner, repository, number) {
+  return getJson(`https://api.github.com/repos/${owner}/${repository}/issues/${number}`)
+}
+
+export async function issueComments(owner, repository, number, maxPages = 10) {
+  const all = []
+  for (let page = 1; page <= maxPages; page += 1) {
+    const batch = await getJson(
+      `https://api.github.com/repos/${owner}/${repository}/issues/${number}/comments?per_page=100&page=${page}`,
+    )
+    if (!Array.isArray(batch) || !batch.length) break
+    all.push(...batch)
+    if (batch.length < 100) break
+  }
+  return all
+}
+
+/**
+ * The current default-branch HEAD of a repository.
+ *
+ * With a token this uses the REST API, which names the default branch
+ * explicitly. Without one it falls back to the repository's commit feed, the
+ * same unauthenticated source the underlying measurement used, because that
+ * feed does not consume the 60-requests-per-hour API allowance.
+ */
+export async function defaultBranchHead(repositoryUrl) {
+  const match = String(repositoryUrl).match(/^https:\/\/github\.com\/([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+?)(?:\.git)?\/?$/)
+  if (!match) throw new GitHubError("usage", `not a GitHub repository URL: ${repositoryUrl}`)
+  const [, owner, repository] = match
+  if (token()) {
+    const meta = await getJson(`https://api.github.com/repos/${owner}/${repository}`)
+    const branch = meta.default_branch
+    const head = await getJson(`https://api.github.com/repos/${owner}/${repository}/commits/${encodeURIComponent(branch)}`)
+    return {
+      source: "api",
+      branch,
+      commit: String(head.sha).toLowerCase(),
+      committedAt: head.commit?.committer?.date || head.commit?.author?.date || null,
+      archived: meta.archived === true,
+      private: meta.private === true,
+    }
+  }
+  const feed = await getText(`https://github.com/${owner}/${repository}/commits.atom`, "application/atom+xml")
+  const commit = feed.match(/<id>tag:github\.com,2008:Grit::Commit\/([0-9a-f]{40})<\/id>/i)?.[1]
+    || feed.match(/\/commit\/([0-9a-f]{40})/i)?.[1]
+  if (!commit) throw new GitHubError("head-unreadable", `cannot read a commit from the commit feed of ${repositoryUrl}`)
+  const branch = feed.match(/<title>Recent Commits to [^:]+:(.+?)<\/title>/)?.[1] || null
+  const committedAt = feed.match(/<updated>([^<]+)<\/updated>/)?.[1] || null
+  return { source: "commits.atom", branch, commit: commit.toLowerCase(), committedAt, archived: null, private: null }
+}

package/tools/marketplace/issue.mjs

@@ -0,0 +1,80 @@
+// Render the submission issue exactly as GitHub's own issue form would render
+// it, from the contract read at the pin, and then prove the result by running
+// the marketplace's own parser over it.
+//
+// Measured reason the rendering is generated rather than hand-written
+// (docs/MEASUREMENTS.md M2): 39 submissions failed on the title prefix alone
+// and 11 open submissions are malformed in the body, one of them by the single
+// word "Suggested" instead of "Suggest". Hand-typing six headings is how that
+// happens. Generating them from the form and then parsing the result with
+// `parseCurrentSubmission` from the same commit removes the class entirely: if
+// the marketplace's parser accepts the body here, it accepts it there.
+
+export const NO_RESPONSE = "_No response_"
+
+export class IssueRenderError extends Error {
+  constructor(code, message) {
+    super(message)
+    this.name = "IssueRenderError"
+    this.code = code
+  }
+}
+
+function heading(text) {
+  return `### ${text}`
+}
+
+/**
+ * @param {object} contract from submissionContract()
+ * @param {{ pluginName: string, repositoryUrl: string, category: string,
+ *           tags: string[], suggestedTag?: string, notes?: string }} input
+ */
+export function renderIssue(contract, input) {
+  const name = String(input.pluginName || "").trim()
+  if (!name) throw new IssueRenderError("plugin-name-missing", "the issue title needs the plugin name")
+  const title = `${contract.titleTemplate}${name}`
+
+  const values = new Map([
+    [contract.headingFor.repository, String(input.repositoryUrl || "").trim()],
+    [contract.headingFor.category, String(input.category || "").trim()],
+    [contract.headingFor.tags, (input.tags || []).join(", ")],
+  ])
+
+  const checklistBlock = contract.checklist.map((item) => `- [X] ${item.label}`).join("\n")
+
+  // Optional free-text fields keyed by heading, so a renamed or reordered form
+  // field cannot silently drop the author's text.
+  const optional = new Map()
+  for (const field of contract.fields) {
+    if (values.has(field.label) || field.label === contract.headingFor.checklist) continue
+    if (field.type === "input") optional.set(field.label, String(input.suggestedTag || "").trim())
+    else optional.set(field.label, String(input.notes || "").trim())
+  }
+
+  const sections = []
+  for (const label of contract.headings) {
+    let body
+    if (label === contract.headingFor.checklist) body = checklistBlock
+    else if (values.has(label)) body = values.get(label)
+    else body = optional.get(label) ?? ""
+    sections.push(`${heading(label)}\n\n${body || NO_RESPONSE}`)
+  }
+
+  return { title, body: `${sections.join("\n\n")}\n` }
+}
+
+/**
+ * Run the marketplace's own submission parser over a rendered issue. The
+ * parser comes from the pinned checkout, so this is the marketplace accepting
+ * or refusing the body, not Omakit's opinion of it.
+ *
+ * @returns {{ ok: true, submission: object } | { ok: false, code: string, message: string }}
+ */
+export function verifyAgainstOfficialParser(contract, issue) {
+  try {
+    const submission = contract.parseCurrentSubmission({ title: issue.title, body: issue.body })
+    return { ok: true, submission }
+  } catch (error) {
+    return { ok: false, code: error.code || "submission-invalid", message: error.message }
+  }
+}

package/tools/marketplace/local-transport.mjs

@@ -0,0 +1,162 @@
+// Local Git transport for the official Omarchy marketplace security baseline.
+//
+// The official snapshot resolver (scripts/security-baseline-scope.mjs at the
+// pinned marketplace commit) takes an injectable `fetchImpl` and asks for:
+//
+//   GET https://api.github.com/repos/{owner}/{repo}
+//   GET https://api.github.com/repos/{owner}/{repo}/commits/{sha}
+//   GET https://api.github.com/repos/{owner}/{repo}/git/trees/{treeSha}?recursive=1
+//   GET https://raw.githubusercontent.com/{owner}/{repo}/{sha}/{path}   (also ranged)
+//
+// This transport answers exactly those requests from a local clone at the exact
+// commit. Nothing is invented beyond repository metadata that cannot be known
+// locally, which the caller records as `assumedByAdapter`. No network, no
+// credentials, no writes.
+
+import { execFileSync } from "node:child_process"
+
+export const ADAPTER_VERSION = 1
+
+export const ASSUMED_BY_ADAPTER = Object.freeze([
+  "repository.private=false",
+  "repository.disabled=false",
+  "repository.archived=false",
+  "tree.truncated=false (the local tree is always complete)",
+])
+
+function git(repoDir, args, encoding = "utf8") {
+  return execFileSync("git", ["-C", repoDir, ...args], {
+    encoding,
+    maxBuffer: 512 * 1024 * 1024,
+    stdio: ["ignore", "pipe", "pipe"],
+  })
+}
+
+function parseRepoUrl(repoUrl) {
+  const url = new URL(repoUrl)
+  const [owner, repository] = url.pathname.replace(/^\/|\/$/g, "").split("/")
+  return { owner, repository: repository.replace(/\.git$/, "") }
+}
+
+function readTree(repoDir, commitSha) {
+  const raw = git(repoDir, ["ls-tree", "-r", "-t", "-l", commitSha])
+  const entries = []
+  for (const line of raw.split("\n")) {
+    if (!line) continue
+    const tab = line.indexOf("\t")
+    const [mode, type, sha, size] = line.slice(0, tab).split(/\s+/)
+    const path = line.slice(tab + 1)
+    const entry = { path, mode, type, sha }
+    if (type === "blob") entry.size = Number(size)
+    entries.push(entry)
+  }
+  return entries
+}
+
+function jsonResponse(body) {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: { "content-type": "application/json" },
+  })
+}
+
+function notFound(what) {
+  return new Response(JSON.stringify({ message: `local transport: ${what}` }), {
+    status: 404,
+    headers: { "content-type": "application/json" },
+  })
+}
+
+function fileResponse(buffer, range) {
+  if (!range) {
+    return new Response(buffer, {
+      status: 200,
+      headers: {
+        "content-type": "text/plain; charset=utf-8",
+        "content-length": String(buffer.length),
+      },
+    })
+  }
+  const match = String(range).match(/^bytes=0-(\d+)$/)
+  if (!match) return new Response("", { status: 416 })
+  const end = Math.min(Number(match[1]), buffer.length - 1)
+  const slice = buffer.subarray(0, end + 1)
+  return new Response(slice, {
+    status: 206,
+    headers: {
+      "content-type": "text/plain; charset=utf-8",
+      "content-length": String(slice.length),
+      "content-range": `bytes 0-${end}/${buffer.length}`,
+    },
+  })
+}
+
+/**
+ * @param {{ repoDir: string, repoUrl: string, commitSha: string, defaultBranch?: string }} options
+ * @returns {{ fetchImpl: Function, stats: { api: number, raw: number } }}
+ */
+export function createLocalTransport({ repoDir, repoUrl, commitSha, defaultBranch }) {
+  const { owner, repository } = parseRepoUrl(repoUrl)
+  let commit = ""
+  try {
+    commit = git(repoDir, ["rev-parse", "--verify", "-q", `${commitSha}^{commit}`]).trim()
+  } catch {
+    commit = ""
+  }
+  if (commit.toLowerCase() !== String(commitSha).toLowerCase()) {
+    throw new Error(`local transport: ${repoDir} does not contain commit ${commitSha}`)
+  }
+  const treeSha = git(repoDir, ["rev-parse", `${commit}^{tree}`]).trim()
+  const tree = readTree(repoDir, commit)
+  const byPath = new Map(tree.map((entry) => [entry.path, entry]))
+  const branch = defaultBranch
+    || (() => {
+      try {
+        return git(repoDir, ["rev-parse", "--abbrev-ref", "HEAD"]).trim()
+      } catch {
+        return "main"
+      }
+    })()
+
+  const stats = { api: 0, raw: 0 }
+  const apiBase = `https://api.github.com/repos/${owner}/${repository}`
+  const rawBase = `https://raw.githubusercontent.com/${owner}/${repository}/${commit}/`
+
+  async function fetchImpl(url, options = {}) {
+    const target = String(url)
+    if (target.startsWith("https://api.github.com/")) {
+      stats.api += 1
+      if (target === apiBase) {
+        return jsonResponse({
+          full_name: `${owner}/${repository}`,
+          private: false,
+          disabled: false,
+          archived: false,
+          default_branch: branch,
+        })
+      }
+      if (target === `${apiBase}/commits/${commit}`) {
+        return jsonResponse({ sha: commit, commit: { tree: { sha: treeSha } } })
+      }
+      if (target === `${apiBase}/git/trees/${treeSha}?recursive=1`) {
+        return jsonResponse({ sha: treeSha, truncated: false, tree })
+      }
+      return notFound(`unexpected API request ${target}`)
+    }
+    if (target.startsWith(rawBase)) {
+      stats.raw += 1
+      const path = target
+        .slice(rawBase.length)
+        .split("/")
+        .map(decodeURIComponent)
+        .join("/")
+      const entry = byPath.get(path)
+      if (!entry || entry.type !== "blob") return notFound(`no blob at ${path}`)
+      const buffer = git(repoDir, ["cat-file", "blob", entry.sha], "buffer")
+      return fileResponse(buffer, options.headers?.Range || options.headers?.range)
+    }
+    return notFound(`unsupported host for ${target}`)
+  }
+
+  return { fetchImpl, stats, commit, treeSha, tree }
+}

package/tools/marketplace/parity-output.mjs

@@ -0,0 +1,26 @@
+import { accessSync, constants, existsSync } from "node:fs"
+import { join, resolve } from "node:path"
+
+export class ParityOutputError extends Error {
+  constructor(message) {
+    super(message)
+    this.name = "ParityOutputError"
+    this.code = "parity-output-required"
+    this.remedy = "omakit parity --out <file>"
+  }
+}
+
+/** Resolve parity evidence before any fetch, refusing a packaged read-only default. */
+export function parityOutput({ repoRoot, out = null }) {
+  if (out) return resolve(out)
+  const evidenceRoot = join(resolve(repoRoot), "docs/evidence")
+  if (!existsSync(evidenceRoot)) {
+    throw new ParityOutputError(`this install has no source-tree evidence directory at ${evidenceRoot}; pass --out <file> for the parity evidence.`)
+  }
+  try {
+    accessSync(evidenceRoot, constants.W_OK)
+  } catch {
+    throw new ParityOutputError(`the measured evidence directory is not writable at ${evidenceRoot}; pass --out <file> for the parity evidence.`)
+  }
+  return join(evidenceRoot, "parity")
+}

package/tools/marketplace/paths.mjs

@@ -0,0 +1,10 @@
+import { homedir } from "node:os"
+import { join, resolve } from "node:path"
+
+/** Omakit's user-writable cache, following XDG with the usual ~/.cache fallback. */
+export function omakitCacheDir(name = "", env = process.env) {
+  const base = env.XDG_CACHE_HOME
+    ? resolve(env.XDG_CACHE_HOME)
+    : join(env.HOME || homedir(), ".cache")
+  return join(base, "omakit", name)
+}