qbit-scripting/github/README.md

# GitHub source importer

Optional `com.kingsrook.qbits:qbit-scripting-github:0.1.0-SNAPSHOT` adapter implements the base QBit's `GitSourceImporter` port. It has no dependency on another QBit's credential registry, UI or runtime. Install it explicitly with `runtime.withImporter(new GitHubSourceImporter(hostManagedGitHubAccess))`.

`GitHubAccess.tokenFor(Actor, scriptId, repository)` must authorize the current actor, project and exact repository on every call, and obtain a read-only short-lived credential from the host's existing managed credential provider. Throw to deny. A null result means the host explicitly authorized anonymous public access. This is not automatic anonymous fallback. Credential text is used only in the trusted Authorization header and is never persisted, logged, returned to a browser or passed to a worker. No new OAuth application, token store or environment-token guessing is implemented.

Imports require a full lowercase 40-character commit SHA. The adapter uses GitHub.com's fixed HTTPS API host, never follows redirects or response-provided URLs, checks returned commit/tree identities, rejects truncated trees, verifies every blob's Git SHA-1 and declared size, and decodes strict UTF-8. It uses the documented [Git commit](https://docs.github.com/en/rest/git/commits), [tree](https://docs.github.com/en/rest/git/trees) and [blob](https://docs.github.com/en/rest/git/blobs) response shapes. Transport trust is GitHub HTTPS; the adapter does not claim verification of a commit author's cryptographic signature.

The selected directory must contain ordinary non-executable `.ts` files and directories only. Symlinks, submodules, archives, manifests, JavaScript, unsupported paths and duplicate case-insensitive paths fail the whole import. Use a dedicated source directory in repositories containing README files or package manifests. No clone, checkout, package installation, build hooks or CI scripts run. Branches and tags are not accepted. Import/sync is an explicit action against an exact new commit; there is no automatic webhook or background fetch.

Bounds: 45-second whole import deadline, at most 15 seconds per HTTP request including body delivery, 1 MiB per encoded response, 1,000 tree entries, 200 source files, 256 KiB per file and 2 MiB decoded source total. Oversized streaming responses cancel before JSON allocation. Hosts still need normal request admission/rate limits. Current repository authorization is reevaluated before each HTTP request; current draft permission and project authorization are reevaluated after network work and before the database transaction commits.

The service writes a core source revision/files and `scripting_import` receipt in one transaction. The receipt stores repository, commit, selected directory, canonical SHA-256, current actor and timestamp. It is provenance, not another byte registry. Use the matching owner schema/migrations for the explicitly qualified H2 or MySQL deployment; archived PostgreSQL SQL is not production backend qualification. A JDBC test proves receipt failure rolls back every source row. An import never compiles, tests, publishes or binds automatically.

From the base directory: `./mvnw -f github/pom.xml verify`. Seven trusted HTTP-response/stream tests pass, including mode/path denial, truncation, tampered blob data, repository denial and subtree selection. No private repository or real external HTTP request was used in tests. Host credential integration and production GitHub transport qualification remain deployment work. The existing semantic UI/UX API and Next editor expose this import through the reviewed core isolation authority.

## Native process clients

The producer registers `scripting_import_commit` on a selected Script record. Its ordinary
EDIT_FORM asks for `owner/repository`, the full lowercase 40-character commit SHA and an optional
TypeScript-only subdirectory. No token, provider URL or actor field is accepted. With no configured
importer preparation refuses; repository access still belongs to the host-managed `GitHubAccess`.

The server retains the expected current revision between prepare and apply. Submit delegates to
the same `ScriptingService.importDraft` used by the semantic API and editor. Stale source, revoked
authoring permission and narrowed credential/channel write ceilings refuse before retrieval;
authority and optimistic revision are checked again in the final transaction. Import creates a
new immutable full draft file set and receipt, preserving prior revisions. The result links that
revision and displays its repository/commit/directory/source hash. Check, test and publish remain
separate actions. CLI, TUI and other QQQ process clients need no Next-specific import workflow.

Native process tests use a trusted source importer fixture with actual owner persistence and
metadata. They do not contact GitHub or establish production credential/transport qualification.