ghimg 0.1.0

package/README.md

@@ -0,0 +1,60 @@
+# ghimg
+
+Upload images to GitHub's `user-attachments` CDN from the command line and get a
+markdown reference back. Replicates GitHub's web UI upload flow, so the resulting
+URLs are scoped to the repository they're uploaded to (private-repo images stay
+private).
+
+## Setup
+
+```bash
+npx ghimg init
+```
+
+The wizard asks for your github.com `user_session` cookie value — copy it from
+devtools (`Application -> Cookies -> https://github.com -> user_session`). It's
+saved to `.env` as `GH_SESSION_TOKEN` and validated against GitHub.
+
+## Usage
+
+```bash
+# repo inferred from the current git remote
+npx ghimg upload screenshot.png
+
+# target a repo explicitly, multiple files at once
+npx ghimg upload --repo owner/repo a.png b.png
+
+# verify the saved token
+npx ghimg check
+```
+
+Each upload prints `![name](https://github.com/user-attachments/assets/...)`.
+
+## Commands
+
+| Command  | Description                                                      |
+| -------- | ---------------------------------------------------------------- |
+| `init`   | Setup wizard for your GitHub session token                       |
+| `upload` | Upload one or more images and print markdown references          |
+| `check`  | Verify the saved token and print the authenticated username      |
+
+All commands accept `--config <path>` to point at a specific `.env` file
+(defaults to `.env` in the current directory). `upload` also takes
+`--repo owner/repo`.
+
+## Requirements
+
+- **Node 22+** — uses global `fetch`, `FormData`, and `Blob`.
+- **[`gh` CLI](https://cli.github.com)**, authenticated — used to resolve the numeric
+  repository ID (works for private repos).
+
+## Security
+
+This tool uses your `user_session` cookie, which is your full authenticated GitHub
+web session — more powerful than a scoped token. It is only ever sent to
+`github.com` and to the presigned S3 URL GitHub returns. The token is stored in
+`.env` (gitignored); don't commit it.
+
+## License
+
+MIT

package/bin/ghimg.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+
+import { init } from '../commands/init.js'
+import { upload } from '../commands/upload.js'
+import { check } from '../commands/check.js'
+
+const command = process.argv[2]
+const args = process.argv.slice(3)
+
+const commands = {
+  init,
+  upload: () => upload(args),
+  check: () => check(args)
+}
+
+// A leading argument that is neither a flag nor a known command is treated as a
+// file path, so `ghimg screenshot.png` is shorthand for `ghimg upload screenshot.png`.
+function looksLikeFile(arg) {
+  return Boolean(arg) && !arg.startsWith('-')
+}
+
+async function main() {
+  try {
+    if (commands[command]) {
+      await commands[command]()
+    } else if (looksLikeFile(command)) {
+      await upload(process.argv.slice(2))
+    } else {
+      console.log(`
+Usage: ghimg [command] <image-path>...
+
+Commands:
+  init                            Setup wizard for your GitHub session token
+  upload [--repo owner/repo]      Upload one or more images, print markdown
+          <image-path>...         (repo defaults to the current git remote)
+  check                           Verify the saved token and print the username
+
+The "upload" command is the default: a first argument that looks like a file is
+uploaded directly. All commands accept --config <path> to point at a specific
+.env file (defaults to .env in the current directory).
+
+Examples:
+  npx ghimg init
+  npx ghimg screenshot.png
+  npx ghimg upload --repo owner/repo a.png b.png
+  npx ghimg check
+`)
+      process.exit(command ? 1 : 0)
+    }
+  } catch (error) {
+    console.error('Error:', error.message)
+    process.exit(1)
+  }
+}
+
+main()

package/commands/check.js

@@ -0,0 +1,13 @@
+import { loadValidatedConfig } from '../lib/config.js'
+import { parseArgs } from '../lib/args.js'
+import { checkValidity } from '../lib/github.js'
+
+export async function check(argv) {
+  const { options } = parseArgs(argv, { flags: ['--config'] })
+
+  const { sessionToken } = loadValidatedConfig(options.config)
+  const username = await checkValidity(sessionToken)
+
+  console.error('Token is valid')
+  if (username) console.log(username)
+}

package/commands/init.js

@@ -0,0 +1,33 @@
+import { intro, outro, password, isCancel, cancel, log, spinner } from '@clack/prompts'
+import { saveConfig } from '../lib/config.js'
+import { checkValidity } from '../lib/github.js'
+
+function required(value) {
+  return value ? undefined : 'Required'
+}
+
+export async function init() {
+  intro('ghimg setup')
+
+  log.info('Copy the "user_session" cookie from github.com:\n  devtools -> Application -> Cookies -> https://github.com -> user_session')
+
+  const token = await password({
+    message: 'GitHub user_session cookie value',
+    validate: required
+  })
+  if (isCancel(token)) return cancel('Setup cancelled')
+
+  saveConfig({ sessionToken: token.trim() })
+
+  const s = spinner()
+  s.start('Validating token')
+  try {
+    const username = await checkValidity(token.trim())
+    s.stop(username ? `Authenticated as ${username}` : 'Token saved (could not read username)')
+  } catch (error) {
+    s.stop(`Saved, but validation failed: ${error.message}`)
+  }
+
+  log.success('Saved to .env')
+  outro('Done. Try: npx ghimg upload screenshot.png')
+}

package/commands/upload.js

@@ -0,0 +1,31 @@
+import { loadValidatedConfig } from '../lib/config.js'
+import { parseArgs } from '../lib/args.js'
+import { resolveRepo, getUploadToken, uploadAsset } from '../lib/github.js'
+
+export async function upload(argv) {
+  const { options, positionals } = parseArgs(argv, {
+    flags: ['--repo', '--config']
+  })
+
+  if (positionals.length === 0) {
+    console.error('Usage: ghimg upload [--repo owner/repo] <image-path>...')
+    process.exit(1)
+  }
+
+  const { sessionToken } = loadValidatedConfig(options.config)
+  const info = await resolveRepo(options.repo)
+  const uploadToken = await getUploadToken(sessionToken, info.owner, info.name)
+
+  let failed = false
+  for (const path of positionals) {
+    try {
+      const { markdown } = await uploadAsset(sessionToken, info, uploadToken, path)
+      console.log(markdown)
+    } catch (error) {
+      console.error(`Error uploading ${path}: ${error.message}`)
+      failed = true
+    }
+  }
+
+  if (failed) process.exit(1)
+}

package/lib/args.js

@@ -0,0 +1,22 @@
+// Split argv into named options and bare positionals, so flags can appear in
+// any order. `flags` take a following value; `booleans` are standalone.
+// Option keys drop the leading '--' (e.g. '--repo' -> 'repo').
+function parseArgs(argv, { flags = [], booleans = [] } = {}) {
+  const options = {}
+  const positionals = []
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if (booleans.includes(arg)) {
+      options[arg.replace(/^--/, '')] = true
+    } else if (flags.includes(arg)) {
+      options[arg.replace(/^--/, '')] = argv[++i]
+    } else {
+      positionals.push(arg)
+    }
+  }
+
+  return { options, positionals }
+}
+
+export { parseArgs }

package/lib/config.js

@@ -0,0 +1,55 @@
+import { z } from 'zod'
+import { existsSync, writeFileSync } from 'fs'
+
+const ENV_FILE = '.env'
+
+const configSchema = z.object({
+  sessionToken: z.string().min(1)
+})
+
+// Load the given .env file (if present), then fall back to whatever is already
+// in the environment.
+function readEnv(envFile) {
+  if (existsSync(envFile)) process.loadEnvFile(envFile)
+  return process.env
+}
+
+function loadConfig(envFile = ENV_FILE) {
+  const env = readEnv(envFile)
+
+  if (!env.GH_SESSION_TOKEN) return null
+
+  const result = configSchema.safeParse({
+    sessionToken: env.GH_SESSION_TOKEN.trim()
+  })
+
+  if (!result.success) {
+    console.error('Configuration validation failed:')
+    console.error(z.prettifyError(result.error))
+    process.exit(1)
+  }
+
+  return result.data
+}
+
+function loadValidatedConfig(envFile = ENV_FILE) {
+  const config = loadConfig(envFile)
+
+  if (!config) {
+    console.error('No session token found. Run "npx ghimg init" first, or set GH_SESSION_TOKEN.')
+    process.exit(1)
+  }
+
+  return config
+}
+
+function saveConfig(config) {
+  try {
+    writeFileSync(ENV_FILE, `GH_SESSION_TOKEN="${config.sessionToken}"\n`)
+  } catch (error) {
+    console.error('Error writing .env file: ' + error.message)
+    process.exit(1)
+  }
+}
+
+export { loadConfig, loadValidatedConfig, saveConfig }

package/lib/github.js

@@ -0,0 +1,164 @@
+import { execa } from 'execa'
+import { readFileSync } from 'fs'
+import { basename, extname } from 'path'
+
+const GITHUB = 'https://github.com'
+const USER_AGENT =
+  'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 ' +
+  '(KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36'
+
+const MIME = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.svg': 'image/svg+xml'
+}
+
+// GitHub requires both cookies for CSRF validation on the upload endpoint.
+function cookieHeader(token) {
+  return `user_session=${token}; __Host-user_session_same_site=${token}`
+}
+
+function ghHeaders(token, owner, repo, extra = {}) {
+  return {
+    Cookie: cookieHeader(token),
+    'User-Agent': USER_AGENT,
+    Origin: GITHUB,
+    Referer: `${GITHUB}/${owner}/${repo}`,
+    'X-Requested-With': 'XMLHttpRequest',
+    ...extra
+  }
+}
+
+// Resolve owner/name (from --repo or the git remote) plus the numeric repo ID.
+// The ID is looked up via the gh CLI, so private repos resolve too.
+async function resolveRepo(repoFlag) {
+  let slug = repoFlag
+
+  if (!slug) {
+    let url
+    try {
+      const { stdout } = await execa('git', ['remote', 'get-url', 'origin'])
+      url = stdout.trim()
+    } catch {
+      throw new Error('not a git repository — pass --repo owner/repo')
+    }
+    const match = url.match(/github\.com[:/](.+?)\/(.+?)(?:\.git)?$/)
+    slug = match ? `${match[1]}/${match[2]}` : ''
+  }
+
+  const [owner, name] = slug.split('/')
+  if (!owner || !name) throw new Error(`could not parse owner/repo from: ${slug || '(empty)'}`)
+
+  let id
+  try {
+    const { stdout } = await execa('gh', ['api', `repos/${owner}/${name}`, '--jq', '.id'])
+    id = Number(stdout.trim())
+  } catch {
+    throw new Error(`failed to look up repo ID for ${owner}/${name} (is the gh CLI installed and authenticated?)`)
+  }
+  if (!id) throw new Error(`unexpected repo ID for ${owner}/${name}`)
+
+  return { owner, name, id }
+}
+
+// Verify a session token by loading the profile page; returns the username.
+async function checkValidity(token) {
+  const response = await fetch(`${GITHUB}/settings/profile`, {
+    headers: { Cookie: cookieHeader(token), 'User-Agent': USER_AGENT },
+    redirect: 'manual'
+  })
+  if (response.status !== 200) {
+    throw new Error(`token is invalid or expired (status ${response.status})`)
+  }
+  const match = (await response.text()).match(/<meta name="user-login" content="([^"]+)"/)
+  return match ? match[1] : ''
+}
+
+// Step 0: scrape the per-repo uploadToken from the repo page.
+async function getUploadToken(token, owner, repo) {
+  const response = await fetch(`${GITHUB}/${owner}/${repo}`, {
+    headers: { Cookie: cookieHeader(token), 'User-Agent': USER_AGENT }
+  })
+  if (!response.ok) {
+    throw new Error(`repo page ${response.status} — do you have access to ${owner}/${repo}?`)
+  }
+  const match = (await response.text()).match(/"uploadToken":"([^"]+)"/)
+  if (!match) {
+    throw new Error(
+      `uploadToken not found — need write access to ${owner}/${repo} ` +
+      `(or, if it enforces SAML SSO, authorize at ${GITHUB}/orgs/${owner}/sso)`
+    )
+  }
+  return match[1]
+}
+
+// Step 1: request the S3 upload policy.
+async function requestPolicy(token, info, uploadToken, file, size, contentType) {
+  const form = new FormData()
+  form.set('name', file)
+  form.set('size', String(size))
+  form.set('content_type', contentType)
+  form.set('authenticity_token', uploadToken)
+  form.set('repository_id', String(info.id))
+
+  const response = await fetch(`${GITHUB}/upload/policies/assets`, {
+    method: 'POST',
+    body: form,
+    headers: ghHeaders(token, info.owner, info.name, { Accept: 'application/json' })
+  })
+  if (response.status !== 201) {
+    throw new Error(`policy request ${response.status}: ${(await response.text()).slice(0, 200)}`)
+  }
+  return response.json()
+}
+
+// Step 2: upload the bytes to the presigned S3 URL (no GitHub cookies here).
+async function uploadToS3(policy, buffer, file, contentType) {
+  const form = new FormData()
+  // Server-provided field order; the file part must come last.
+  for (const [key, value] of Object.entries(policy.form)) form.set(key, value)
+  form.set('file', new Blob([buffer], { type: contentType }), file)
+
+  const response = await fetch(policy.upload_url, {
+    method: 'POST',
+    body: form,
+    headers: { Origin: GITHUB, 'User-Agent': USER_AGENT }
+  })
+  if (![200, 201, 204].includes(response.status)) {
+    throw new Error(`S3 upload ${response.status}: ${(await response.text()).slice(0, 300)}`)
+  }
+}
+
+// Step 3: finalize the asset and return its public reference.
+async function finalizeUpload(token, info, policy) {
+  const form = new FormData()
+  form.set('authenticity_token', policy.asset_upload_authenticity_token)
+
+  const response = await fetch(`${GITHUB}/upload/assets/${policy.asset.id}`, {
+    method: 'PUT',
+    body: form,
+    headers: ghHeaders(token, info.owner, info.name, { Accept: 'application/json' })
+  })
+  if (response.status !== 200) {
+    throw new Error(`finalize ${response.status}: ${(await response.text()).slice(0, 200)}`)
+  }
+  return response.json()
+}
+
+// Upload one image through the full flow and return its markdown reference.
+async function uploadAsset(token, info, uploadToken, path) {
+  const buffer = readFileSync(path)
+  const file = basename(path)
+  const contentType = MIME[extname(path).toLowerCase()] ?? 'application/octet-stream'
+
+  const policy = await requestPolicy(token, info, uploadToken, file, buffer.length, contentType)
+  await uploadToS3(policy, buffer, file, contentType)
+  const { href, name } = await finalizeUpload(token, info, policy)
+
+  return { markdown: `![${name}](${href})`, url: href, name }
+}
+
+export { resolveRepo, checkValidity, getUploadToken, uploadAsset }

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "ghimg",
+  "version": "0.1.0",
+  "description": "Upload images to GitHub from the command line and print markdown references.",
+  "type": "module",
+  "bin": {
+    "ghimg": "bin/ghimg.js"
+  },
+  "files": [
+    "bin",
+    "commands",
+    "lib"
+  ],
+  "scripts": {
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
+  },
+  "keywords": [
+    "github",
+    "image",
+    "upload",
+    "markdown",
+    "cli",
+    "user-attachments"
+  ],
+  "author": "Nico Devs <hi@nicodevs.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nicodevs/ghimg.git"
+  },
+  "bugs": {
+    "url": "https://github.com/nicodevs/ghimg/issues"
+  },
+  "homepage": "https://github.com/nicodevs/ghimg#readme",
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.11.0",
+    "execa": "^9.0.0",
+    "zod": "^4.3.4"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "eslint": "^9.39.2",
+    "globals": "^17.3.0"
+  }
+}