Add public API-only Spritesmith client for raster and vector sprites

.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+permissions:
+  contents: read
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  check:
+    name: Check
+    runs-on: ubuntu-24.04
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        timeout-minutes: 3
+      - uses: jdx/mise-action@7a4e45a543138629540c9a1616d08632b893e492 # v5.0.1
+        with:
+          version: 2026.9.12
+        timeout-minutes: 15
+      - run: make install
+        timeout-minutes: 15
+      - run: make check
+        timeout-minutes: 20
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        timeout-minutes: 5
+        with:
+          name: spritesmith-cli-${{ github.sha }}
+          path: dist/
+          if-no-files-found: error
+          retention-days: 7

.gitignore

@@ -0,0 +1,7 @@
+/dist/
+/.artifacts/
+*.png
+*.svg
+.env
+
+spritesmith-alpha.png

.mise.toml

@@ -0,0 +1,5 @@
+[tools]
+go = "1.27.2"
+python = "3.13.11"
+actionlint = "1.7.12"
+"go:golang.org/x/vuln/cmd/govulncheck" = "1.7.0"

AGENTS.md

@@ -0,0 +1,3 @@
+# Go HAS CHANGED
+
+Read the exact versioned docs at https://go.dev/doc/go1.27 before writing any code.

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

Makefile

@@ -0,0 +1,33 @@
+SHELL := /bin/bash
+.SHELLFLAGS := -eu -o pipefail -c
+.DEFAULT_GOAL := help
+.NOTPARALLEL:
+VERSION ?= dev
+.PHONY: help install lint unit integration test build artifact-check vuln check dev stop clean
+help:
+	@echo 'make check: lint, race tests, five-platform archives, artifact verification, vulnerability scan'
+install:
+	mise trust .mise.toml
+	mise install
+	mise exec -- go mod download
+lint:
+	mise exec -- bash scripts/lint.sh
+	mise exec -- actionlint
+unit:
+	mise exec -- go test -race -count=1 ./internal/token ./cmd/spritesmith
+integration:
+	mise exec -- go test -race -count=1 ./internal/client
+test: unit integration
+build:
+	mise exec -- env VERSION="$(VERSION)" bash scripts/build.sh
+artifact-check:
+	mise exec -- python3 scripts/check-artifacts.py
+vuln:
+	mise exec -- govulncheck ./...
+check: lint test build artifact-check vuln
+dev:
+	mise exec -- go run ./cmd/spritesmith $(ARGS)
+stop:
+	@echo 'unsupported: the CLI owns no background service'
+clean:
+	mise exec -- python3 -c 'import shutil; [shutil.rmtree(p, ignore_errors=True) for p in ("dist", ".artifacts")]'

README.md

@@ -1 +1,45 @@
-# spritesmith
+# Spritesmith
+
+Command-line client for the Spritesmith API. Create raster or vector sprites and download finished PNG or SVG files.
+
+The client requires an API service and an account token. It does not contain a local renderer or generation engine.
+
+## Install
+
+With Go 1.27.2 or later:
+
+```sh
+go install github.com/aviorstudio/spritesmith/cmd/spritesmith@latest
+```
+
+## Configure
+
+Set `SPRITESMITH_API_BASE` to your service URL and `SPRITESMITH_API_TOKEN` to your account's Clerk API key. The token can also live in a private `spritesmith/token` file under your operating system's user configuration directory. Run `spritesmith --help` to see its path. Token files must not be accessible to other users.
+
+Hosted tokens require HTTPS. Loopback HTTP is supported for local development.
+
+## Create sprites
+
+```sh
+spritesmith prompt --operation-id hero-v1 --out hero.png 'A small forest ranger'
+spritesmith prompt --kind vector --format svg --operation-id emblem-v1 --out emblem.svg 'A golden shield emblem'
+spritesmith prompt --kind vector --format png --out emblem.png 'A golden shield emblem'
+spritesmith image --out ranger.png reference.png
+```
+
+Flags come before the prompt or image filename. Vector creation requires a prompt; an image may be supplied as a reference.
+
+Raster sprites export as PNG. Vector sprites export as SVG or PNG. SVG contains editable artwork geometry.
+
+Generation runs as a server job. The client waits for completion and downloads the requested file. Retain `--operation-id` and reuse it with the same input after an interruption. Existing output files are never overwritten. An uncertain job requires reconciliation; the client does not automatically submit another paid request.
+
+The default API is `http://127.0.0.1:8080`; configure your hosted service explicitly. Default output is `spritesmith-alpha.png`, or `spritesmith.svg` for SVG downloads.
+
+## Development
+
+```sh
+make install
+make check
+```
+
+Checks include Go race tests, HTTP client integration tests, five platform archives, checksums, source identity verification, and vulnerability scanning. The client builds independently of private repositories.