feat(sculptok): add sculptok

[vcolombo]

sculptok

SculptOK AI depth-map, relief, STL and 3D generation CLI — the first CLI and MCP for SculptOK. Turn a local image into a depth map, printable STL, or 3D model in one command, with credit-cost preflight and a local SQLite job store no other tool has.

API: sculptok | Category: ai | Press version: 4.24.0
Spec: Hand-authored internal YAML from the official api-open REST docs (no public OpenAPI exists)

Publication Path

New print — no merged CLI and no existing PR matched this slug (greenfield; no prior SculptOK CLI/MCP/SDK anywhere).

CLI Shape

$ sculptok-pp-cli --help
(eval):6: no such file or directory: /Users/colombov/printing-press/.publish-repo-sculptok-0bb69f37/library/ai/sculptok/sculptok-pp-cli

Novel Commands

Command	Name	Description
generate depthmap	One-command depth-map generate	Upload a local image, submit, auto-poll, download depth-map candidates in one command.
generate stl	One-command image-to-STL	Local image straight to a printable STL with thickness/width/invert/scale flags.
generate threed	One-command 3D model generate	Local image to a 3D model at basic/standard/high precision, polled and downloaded.
cost	Credit-cost preflight estimator	Estimate credits a draw/batch would cost vs your live balance before spending.
analytics	Spend analytics by kind and day	Aggregate locally synced credit events to see where credits went.
reconcile	Reconcile credits against jobs	Cross-check synced credit charges against produced jobs to find unmatched spend.
search	Offline job search	Full-text search the local mirror of draws/credit events without any API call.

Also ships the full official api-open surface (credits balance/history, draw depthmap/restore/threed/stl/status, drawings list) plus a hand-built submit→poll workflow, credit-cost-aware generation, and a pure-Go SQLite store.

What This CLI Does

The first CLI and MCP for SculptOK. SculptOK's web tool is async and credit-metered: upload, submit a draw, wait, refresh, then download. This CLI collapses that into one command (generate depthmap/stl/threed/restore) that uploads a local image, previews the credit cost, polls to completion, and saves the results. Every draw, credit event, and upload is mirrored into a local SQLite database for offline search, spend analytics by kind, and credit/job reconciliation.

Manuscripts

• Research Brief
• Absorb Manifest
• Novel Features Brainstorm
• Build Log
• Shipcheck Proof
• Live Acceptance Report
• Polish Pass
• Code Review Findings
• Phase 5 Acceptance (JSON)

Validation Results

Check	Result
Manifest	PASS
Transcendence	PASS
Phase 5	PASS
go mod tidy	PASS
govulncheck (this CLI only, reachable)	PASS
go vet	PASS
go build	PASS
--help	PASS
--version	PASS
verify-skill	PASS
Manuscripts	PRESENT

Publish Live Gate

Full live dogfood reran at publish time against the real SculptOK API and passed (64 passed / 0 failed / 49 skipped). A live depth-map generation (upload→submit→poll→download→persist) was verified end-to-end during generation, producing a real 1280×1280 depth map for 10 credits. Generation commands are guarded against credit spend under the verify/dogfood harness.

Notes

• The api-open API returns HTTP 200 for all responses with status in a {code,msg,data} envelope; the hand-built workflow/store commands treat code != 0 as a typed error.
• Two minor non-blocking gaps documented in the acceptance report: credits balance (generated command) serves a cached GET — use --no-cache or cost for a fresh balance; generated absorbed commands surface the full envelope (data is correct/agent-parseable).

[github-actions]

@greptileai review

_{Auto-nudge from greptile-policy-gate.yml because no Greptile Review check appeared for d9eb9fbc577759464bd83b7c38f2105e88364545 after 186s. This usually means the PR is over Greptile auto-review size cap; manual triggers bypass it.}

[Copilot]

Pull request overview

Adds a new published CLI + MCP server under library/ai/sculptok/ for the SculptOK api-open surface, including hand-authored workflow commands and a local SQLite mirror to support offline operations in the printed catalog.

Changes:

• Introduces the SculptOK printed CLI (sculptok-pp-cli) and MCP server (sculptok-pp-mcp) with generated endpoint coverage plus hand-authored “generate/cost/search/analytics/reconcile/sync” workflows.
• Adds a pure-Go SQLite store + tests to persist jobs/credit events/drawings for offline querying and reporting.
• Includes publish artifacts and provenance (manuscripts, patch index entries, goreleaser/golangci configs, NOTICE/AGENTS/release-ledger skeletons).

Reviewed changes

Copilot reviewed 109 out of 111 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
library/ai/sculptok/NOTICE	Adds NOTICE for the new printed CLI directory.
library/ai/sculptok/mcp-descriptions.json	Adds MCP tool description overrides (e.g., credits_balance).
library/ai/sculptok/manifest.json	Adds MCP manifest for sculptok-pp-mcp (entrypoint + required user config).
library/ai/sculptok/Makefile	Adds local build/test/lint/install targets for CLI and MCP binaries.
library/ai/sculptok/internal/types/types.go	Adds basic API data types for credits/drawings.
library/ai/sculptok/internal/store/store_test.go	Adds store tests for upsert/list/search/analytics/reconcile/read-only open behavior.
library/ai/sculptok/internal/sculptok/client_test.go	Adds httptest-based client tests (envelope errors, submit/status/upload, paging).
library/ai/sculptok/internal/mcp/cobratree/walker.go	Adds Cobra-tree walker registering shell-out MCP tools for CLI commands.
library/ai/sculptok/internal/mcp/cobratree/typemap.go	Adds flag→MCP schema mapping for Cobra/pflag flags.
library/ai/sculptok/internal/mcp/cobratree/shellout.go	Adds MCP shell-out execution, root-flag blocking, and CLI arg synthesis.
library/ai/sculptok/internal/mcp/cobratree/names.go	Adds tool-name normalization for command paths.
library/ai/sculptok/internal/mcp/cobratree/cli_path.go	Adds companion CLI path resolution (sibling/env/PATH).
library/ai/sculptok/internal/mcp/cobratree/classify.go	Adds command classification (endpoint/framework/novel/hidden) for MCP mirroring.
library/ai/sculptok/internal/cliutil/verifyenv.go	Adds verifier/dogfood env-var gates used by generated and hand-authored commands.
library/ai/sculptok/internal/cliutil/text.go	Adds text normalization + stored-time parsing + auth/error helpers.
library/ai/sculptok/internal/cliutil/ratelimit.go	Adds adaptive limiter + Retry-After parsing + backoff helpers.
library/ai/sculptok/internal/cliutil/probe.go	Adds lightweight reachability probing helper.
library/ai/sculptok/internal/cliutil/odata_date.go	Adds OData date parsing helper.
library/ai/sculptok/internal/cliutil/odata_date_test.go	Adds tests for OData date parsing behavior.
library/ai/sculptok/internal/cliutil/jwtshape.go	Adds JWT shape heuristics + cookie-jar scanning helper.
library/ai/sculptok/internal/cliutil/jwtshape_test.go	Adds tests for JWT shape checks and cookie-jar extraction.
library/ai/sculptok/internal/cliutil/fanout.go	Adds generic bounded-concurrency fanout runner with deterministic error reporting.
library/ai/sculptok/internal/cliutil/extractnumber.go	Adds JSON number/string numeric extractors for loose-typed JSON.
library/ai/sculptok/internal/cliutil/extractnumber_test.go	Adds tests for ExtractNumber/ExtractInt edge cases.
library/ai/sculptok/internal/cliutil/duration.go	Adds duration parsing that extends stdlib with d/w suffixes.
library/ai/sculptok/internal/cliutil/duration_test.go	Adds tests for loose duration parsing.
library/ai/sculptok/internal/client/client_verify_short_circuit_test.go	Adds tests pinning verify-mode mutating-verb short-circuit behavior.
library/ai/sculptok/internal/client/client_test.go	Adds tests for response-body truncation behavior.
library/ai/sculptok/internal/cli/which_test.go	Adds tests for the which command ranking/index behavior.
library/ai/sculptok/internal/cli/version.go	Adds version command implementation and build-time override hook.
library/ai/sculptok/internal/cli/truncate_json_array.go	Adds hand-authored helper used by generated list commands to enforce --limit.
library/ai/sculptok/internal/cli/sync.go	Adds hand-authored sync from free history endpoints into the local store.
library/ai/sculptok/internal/cli/search.go	Adds offline search across local jobs/credits/drawings.
library/ai/sculptok/internal/cli/search_test.go	Adds placeholder skipped test for novel search command.
library/ai/sculptok/internal/cli/sculptok_shared_test.go	Adds tests for shared SculptOK workflow helpers (cost, image field, URL check).
library/ai/sculptok/internal/cli/reconcile.go	Adds offline reconcile command (credit charges without matching local job).
library/ai/sculptok/internal/cli/reconcile_test.go	Adds placeholder skipped test for novel reconcile command.
library/ai/sculptok/internal/cli/promoted_drawings.go	Adds generated/presented drawings list command wrapper.
library/ai/sculptok/internal/cli/import.go	Adds generic JSONL import framework command (POST per record).
library/ai/sculptok/internal/cli/generate.go	Adds generate command group wiring for depthmap/stl/threed/restore.
library/ai/sculptok/internal/cli/generate_threed.go	Adds hand-authored image→3D workflow command.
library/ai/sculptok/internal/cli/generate_threed_test.go	Adds placeholder skipped test for generate threed command.
library/ai/sculptok/internal/cli/generate_stl.go	Adds hand-authored image→STL workflow command.
library/ai/sculptok/internal/cli/generate_stl_test.go	Adds placeholder skipped test for generate stl command.
library/ai/sculptok/internal/cli/generate_restore.go	Adds hand-authored restore (bg removal / HD restore) workflow command.
library/ai/sculptok/internal/cli/generate_depthmap.go	Adds hand-authored depthmap workflow command.
library/ai/sculptok/internal/cli/generate_depthmap_test.go	Adds placeholder skipped test for generate depthmap command.
library/ai/sculptok/internal/cli/draw.go	Adds generated hidden draw command group for raw async submit/status endpoints.
library/ai/sculptok/internal/cli/draw_status.go	Adds generated draw status endpoint command.
library/ai/sculptok/internal/cli/deliver.go	Adds --deliver sink parsing and delivery implementations (stdout/file/webhook).
library/ai/sculptok/internal/cli/credits.go	Adds generated hidden credits command group.
library/ai/sculptok/internal/cli/credits_history.go	Adds generated credits history endpoint command.
library/ai/sculptok/internal/cli/credits_balance.go	Adds generated credits balance endpoint command.
library/ai/sculptok/internal/cli/cost.go	Adds hand-authored cost estimator comparing expected spend vs live balance.
library/ai/sculptok/internal/cli/cost_test.go	Adds placeholder skipped test for novel cost command.
library/ai/sculptok/internal/cli/auth.go	Adds auth management commands (setup/status/set-token/logout).
library/ai/sculptok/internal/cli/api_discovery.go	Adds API discovery browser (api command) for hidden interface endpoints.
library/ai/sculptok/internal/cli/analytics.go	Adds offline analytics aggregation over locally synced credit events.
library/ai/sculptok/internal/cli/analytics_test.go	Adds placeholder skipped test for novel analytics command.
library/ai/sculptok/internal/cli/agent_context.go	Adds machine-readable agent-context JSON surface for runtime introspection.
library/ai/sculptok/internal/cache/cache.go	Adds file-based response cache implementation.
library/ai/sculptok/go.mod	Adds Go module definition and dependencies for the new CLI/MCP.
library/ai/sculptok/cmd/sculptok-pp-mcp/main.go	Adds MCP server entrypoint with stdio/http transport selection.
library/ai/sculptok/cmd/sculptok-pp-cli/main.go	Adds CLI entrypoint delegating to internal/cli.Execute().
library/ai/sculptok/CHANGELOG.md	Adds release-ledger changelog skeleton (automation-owned).
library/ai/sculptok/AGENTS.md	Adds per-CLI agent guide describing runtime introspection and patching expectations.
library/ai/sculptok/.printing-press.json	Adds provenance manifest for the printed CLI/MCP (run_id, spec checksum, novel features, etc.).
library/ai/sculptok/.printing-press-tools-polish.json	Adds tools polish metadata artifact from generation.
library/ai/sculptok/.printing-press-release.json	Adds release-ledger skeleton for post-merge automation to populate.
library/ai/sculptok/.printing-press-pii-polish.json	Adds PII polish metadata artifact from generation.
library/ai/sculptok/.printing-press-patches/sculptok-truncate-json-array-helper.json	Records the local patch providing truncateJSONArray to fix generator gap.
library/ai/sculptok/.printing-press-patches/sculptok-store-and-generate-workflow.json	Records the local patch implementing store + workflow/novel commands that must survive regen.
library/ai/sculptok/.printing-press-patches/.gitkeep	Ensures patch directory is tracked even when empty.
library/ai/sculptok/.manuscripts/20260622-164426-352dd01a/research/2026-06-22-170804-novel-features-brainstorm.md	Adds research brainstorming manuscript.
library/ai/sculptok/.manuscripts/20260622-164426-352dd01a/research/2026-06-22-170804-feat-sculptok-pp-cli-brief.md	Adds research brief manuscript.
library/ai/sculptok/.manuscripts/20260622-164426-352dd01a/research/2026-06-22-170804-feat-sculptok-pp-cli-absorb-manifest.md	Adds absorb/transcendence manifest manuscript.
library/ai/sculptok/.manuscripts/20260622-164426-352dd01a/proofs/phase5-acceptance.json	Adds phase-5 acceptance proof JSON.
library/ai/sculptok/.manuscripts/20260622-164426-352dd01a/proofs/phase-4.95-findings.md	Adds documented code review findings from generation.
library/ai/sculptok/.manuscripts/20260622-164426-352dd01a/proofs/2026-06-22-170804-fix-sculptok-pp-cli-shipcheck.md	Adds shipcheck proof manuscript.
library/ai/sculptok/.manuscripts/20260622-164426-352dd01a/proofs/2026-06-22-170804-fix-sculptok-pp-cli-polish.md	Adds polish pass proof manuscript.
library/ai/sculptok/.manuscripts/20260622-164426-352dd01a/proofs/2026-06-22-170804-fix-sculptok-pp-cli-build-log.md	Adds build-log proof manuscript.
library/ai/sculptok/.manuscripts/20260622-164426-352dd01a/proofs/2026-06-22-170804-fix-sculptok-pp-cli-acceptance.md	Adds live acceptance proof manuscript.
library/ai/sculptok/.manuscripts/20260622-164426-352dd01a/discovery/api-contract-verified.md	Adds verified API contract notes (envelope, endpoints, pricing).
library/ai/sculptok/.goreleaser.yaml	Adds goreleaser configuration building both CLI and MCP binaries.
library/ai/sculptok/.golangci.yml	Adds golangci-lint configuration enabling common linters + goimports formatting.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[greptile-apps]

Greptile Summary

This PR introduces the first CLI and MCP for SculptOK — a greenfield Go module that wraps SculptOK's async, credit-metered API into a single-command workflow (upload → submit → poll → download) backed by a local SQLite job store for offline search, spend analytics, and credit reconciliation.

• Core workflow (sculptok_shared.go, sculptok/client.go): upload, submit, adaptive-rate-limit polling, job persistence, and CDN download are all implemented correctly; previously-flagged issues (filepath.Ext on query-string URLs, HTTP error-body writes, batch all-failure exit code, LIKE metacharacter escaping) have been addressed.
• search command (search.go): the --type credits path fetches the N most-recent credit events then filters in-memory, making --limit a search-window rather than a result cap — unlike the jobs path which applies SQL LIKE before the limit. Older matching events are silently missed.
• generate stl (generate_stl.go): the recorded map that serialises command flags into the SQLite params column is absent, so every STL job is stored with params={}, making offline search by STL parameters impossible.

Confidence Score: 4/5

Safe to merge with the search.go credit-window issue tracked for a follow-up fix; no data corruption or API-spend risk introduced.

The credits search path in search.go applies --limit as a search-window rather than a result cap, meaning a user searching for an older credit event with the default --limit 20 will silently see zero results even when matching records exist in the local store. The generate stl command does not persist its flag values to the SQLite params column, unlike every other generate subcommand. All other workflow logic, API client behaviour, store operations, and output handling reviewed cleanly.

library/ai/sculptok/internal/cli/search.go (credit search window semantics) and library/ai/sculptok/internal/cli/generate_stl.go (missing recorded params map)

Important Files Changed

Filename	Overview
library/ai/sculptok/internal/cli/sculptok_shared.go	Core generate workflow (upload→submit→poll→persist→download). Previously-flagged issues with filepath.Ext, HTTP error-body writes, and batch all-failure exit code are now addressed. Logic looks correct.
library/ai/sculptok/internal/store/store.go	Pure-Go SQLite store with LIKE-metacharacter escaping now fixed. Unbounded jobs SELECT in Reconcile and the absence of SQL-level credit-event search remain; credit search gap surfaces as a user-facing P1 in search.go.
library/ai/sculptok/internal/cli/search.go	Offline search command: jobs path uses SQL LIKE (limit = result cap), credits path uses in-memory filter on the N most-recent events (limit = search window). Inconsistency silently misses older matching credit events with the default --limit 20.
library/ai/sculptok/internal/cli/generate_stl.go	STL generate command omits the recorded field, so all persisted STL jobs have params={} in the local store, unlike depthmap/threed which record their key flags for offline search.
library/ai/sculptok/internal/sculptok/client.go	Hand-authored API client: upload, submit, poll, and list-page. Rate-limit retry, envelope unwrapping, and context propagation all look correct.
library/ai/sculptok/internal/config/config.go	Config load/save with env-var precedence and agentcookie integration. Unreachable second nil-check in AuthHeader is a minor dead-code issue flagged in a prior review thread.
library/ai/sculptok/internal/cli/sync.go	Paginates credit events and drawings into local SQLite. Per-row upsert errors are silently swallowed but individual row failures are non-critical; overall logic is sound.
library/ai/sculptok/internal/cli/reconcile.go	Reconcile cross-checks credit events against local jobs. Correctly respects the store Reconcile API; the unbounded jobs table scan is a store-layer concern flagged in a prior thread.
library/ai/sculptok/internal/cli/cost.go	Credit-cost preflight estimator: batch counting, cost table lookup, and live-balance comparison all look correct.
library/ai/sculptok/internal/cli/deliver.go	Webhook delivery uses http.NewRequest without a context (flagged in a prior thread); file delivery is atomic (tmp+rename). No new issues.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant User
    participant CLI as sculptok-pp-cli
    participant API as SculptOK API
    participant DB as Local SQLite

    User->>CLI: generate depthmap/stl/threed photo.jpg
    CLI->>CLI: credit preflight (drawCost)
    CLI->>API: POST /image/upload (multipart)
    API-->>CLI: "{src: "https://..."}"
    opt --restore-first
        CLI->>API: POST /draw/hd/prompt
        API-->>CLI: "{promptId}"
        loop poll until done
            CLI->>API: "GET /draw/prompt?uuid=..."
            API-->>CLI: "{status, imgRecords}"
        end
        CLI->>CLI: use restored imageUrl
    end
    CLI->>API: POST /draw/prompt (or /stl/prompt, /3d/prompt)
    API-->>CLI: "{promptId}"
    CLI->>DB: "UpsertJob(status=submitted)"
    loop poll until imgRecords present
        CLI->>API: "GET /draw/prompt?uuid=..."
        API-->>CLI: "{status, imgRecords}"
    end
    CLI->>DB: "UpsertJob(status=completed, resultUrls)"
    opt --out dir set
        CLI->>API: GET result URL (CDN)
        API-->>CLI: file bytes
        CLI->>CLI: write to outDir/kind-id-N.ext
    end
    CLI->>User: JSON or human-readable output

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant User
    participant CLI as sculptok-pp-cli
    participant API as SculptOK API
    participant DB as Local SQLite

    User->>CLI: generate depthmap/stl/threed photo.jpg
    CLI->>CLI: credit preflight (drawCost)
    CLI->>API: POST /image/upload (multipart)
    API-->>CLI: "{src: "https://..."}"
    opt --restore-first
        CLI->>API: POST /draw/hd/prompt
        API-->>CLI: "{promptId}"
        loop poll until done
            CLI->>API: "GET /draw/prompt?uuid=..."
            API-->>CLI: "{status, imgRecords}"
        end
        CLI->>CLI: use restored imageUrl
    end
    CLI->>API: POST /draw/prompt (or /stl/prompt, /3d/prompt)
    API-->>CLI: "{promptId}"
    CLI->>DB: "UpsertJob(status=submitted)"
    loop poll until imgRecords present
        CLI->>API: "GET /draw/prompt?uuid=..."
        API-->>CLI: "{status, imgRecords}"
    end
    CLI->>DB: "UpsertJob(status=completed, resultUrls)"
    opt --out dir set
        CLI->>API: GET result URL (CDN)
        API-->>CLI: file bytes
        CLI->>CLI: write to outDir/kind-id-N.ext
    end
    CLI->>User: JSON or human-readable output

Loading

_{Reviews (4): Last reviewed commit: "feat(sculptok): add sculptok" | Re-trigger Greptile}

[vcolombo]

Addressed review findings in d7ca10fc:

• P2 (store.go) LIKE metacharacters not escaped — SearchJobs now escapes %/_/\ in the term and uses ESCAPE '\' so queries match literally.
• filepath.Ext on URL with query string (sculptok_shared.go) — strip ?/# before reading the download extension.
• Reconcile loads all job prompt_ids — intentional: the join needs every prompt_id to match credit-event remarks, and it is the user's own bounded local jobs table, loaded once (not per-event).

The remaining suggestions (config.go dead-var, deliver.go context, auth.go import grouping, cliutil/text.go regexp compile, cobratree search classification, draw.go group annotation) are in generator-owned/templated files (internal/cliutil, internal/mcp/cobratree, and other Generated by CLI Printing Press files). Per the printing-press contract these are not hand-patched in the printed CLI; they're filed as upstream-generator retro candidates so the fix lands for every future CLI rather than diverging this one.

[github-actions]

@greptileai review

_{Auto-nudge from greptile-policy-gate.yml because no Greptile Review check appeared for d7ca10fc3ac692303a9bf396d565786aa119ebb3 after 187s. This usually means the PR is over Greptile auto-review size cap; manual triggers bypass it.}

[vcolombo]

Fixed the P1 in 1760a4f0: downloadResults now checks resp.StatusCode >= 400 immediately after the request and returns an error (closing the body) before creating the output file, so an expired-presigned-URL 403 / 404 / 5xx CDN error body can no longer be silently written into a .stl/.png and reported as a successful download.

[github-actions]

@greptileai review

_{Auto-nudge from greptile-policy-gate.yml because no Greptile Review check appeared for 1760a4f03122b932ef5074eb14488305e4e8112c after 184s. This usually means the PR is over Greptile auto-review size cap; manual triggers bypass it.}

[vcolombo]

Fixed the batch all-failure P1 in 4982e900: when --batch runs and every draw fails, executeGenerate now returns a non-zero error (after still printing the JSON summary with fetch_failures), so $? reflects the total failure. The earlier downloadResults P1 was fixed in 1760a4f and is no longer flagged by the latest review.

[github-actions]

@greptileai review

_{Auto-nudge from greptile-policy-gate.yml because no Greptile Review check appeared for 4982e9002b62a6e57622b77caef7c13d3f5737dc after 186s. This usually means the PR is over Greptile auto-review size cap; manual triggers bypass it.}