diff --git a/README.md b/README.md index 5322ae3..5c97263 100644 --- a/README.md +++ b/README.md @@ -1,72 +1,30 @@ # zixcel-github -A typed GitHub API wrapper for normalized observations, a closed set of operations and backend invocation through opaque connection references. Public contracts contain no caller-specific packages, runtime grants, workflows or user authorization concepts. +Build and validate typed GitHub requests for repository observation and explicitly enabled operations. -```bash -cargo run --offline -- doctor -cargo run --offline -- capabilities -cargo run --offline -- validate examples/config.toml -cargo run --offline -- plan examples/config.toml -cargo run --offline -- check-request examples/push-request.json -``` - -Only opaque `connection_ref` values are accepted, never credentials. OAuth, secret resolution and HTTP/Git transport belong to Crowsi/Zixcel worker boundaries. `execute_api_request` passes validated closed requests to an injected `GitHubBackend`; higher adapters authorize the caller. No path dependencies on other local repositories are used. - -`parse_config` validates closed TOML up to 1 MiB; `build_plan` is independent of repository ordering. No HTTP or secret resolver is linked; execution is restricted to an injected backend trait. The source manifest now targets crates.io. The public publication workflow is prepared locally and remains disabled pending name ownership, trusted-publisher setup, and exact package review. Existing private-registry artifacts have not been replaced or activated. +## What you can do -## Responsibilities +- Describe reads and supported repository changes. +- Validate request scope and parse provider results. -- Zixcel: API requests/receipts, operation validation and backend ports. -- Crowsi: connection resolution, credentials, transport and signed invocation boundaries. -- Caller adapters: conversion of user/workflow authority into API requests. +## Current scope -The crate does not identify adapter types or products. Write operations include private repository creation, source snapshots, issues/PRs, workflow dispatch and private repository deletion. +A caller supplies the authenticated transport and allowed operation configuration. Creation and deletion require explicit permission for the exact target. -## Quality gate +Package distribution is not activated by this documentation. Use the checked-in source and the declared dependency versions; published availability must be verified separately. -These checks are local and do not connect to GitHub: - -```bash -# WONDERLAND_ROOT is the workspace checkout root. -"$WONDERLAND_ROOT/bin/verify-repositories" --rust --tier standard -``` +## Getting started -## Local policy and synchronization - -`allowed_actions` is the local write ceiling. Missing or empty lists allow reads only. `ConnectorConfig::authorize_request` matches connection, organization and repository. Signed upstream grants and GitHub permissions remain separate requirements. +Install Rust 1.97 or newer and make the declared dependencies available. Use the configured private registry when a dependency is not distributed publicly. Run from this repository: ```sh -cargo run -- check-configured-request examples/write-config.toml examples/create-request.json +cargo test --locked ``` -`execute_configured_request` validates configuration before invoking the backend. Production Crowsi transport applies the same checks in verify and execute. `execute_api_request` is a lower-level typed port; callers must apply authorization and local ceilings. - -`create-private-repository`, `push-repository-snapshot` and `delete-repository` are independent permissions. Deletion requires `github-repository-administration/delete-resource`, an expected repository ID and a backup-declaration SHA-256. - -`zixcel-repository-security prepare-snapshot` prepares a checked complete-source artifact. References use `sha256:<64hex>`; digest fields use bare 64-character hex. Store `<64hex>.json` in Crowsi's artifact store. Hash the current remote commit SHA string using SHA-256 and use the bare digest in `expected_remote: {state: exact, commit_sha256: ...}`. Reobserve after changes. Force updates are never used. - -Creation distinguishes users and organizations; organizations use `/orgs/{owner}/repos`. Because Git Data API cannot operate on an empty repository, creation initializes a commit; observe its head before pushing a complete snapshot. Creation and synchronization are separate signed operations. Snapshots do not transfer local Git history. History-preserving pushes require Crowsi Git transport and separate history inspection. - -## Deletion backup declaration - -```json -{"schema":"zixcel://github/deletion-backup/v1","repository_id":"12345","owner":"example-org","repository":"example-api","bundle_digest_sha256":"sha256:<64hex>"} -``` - -The declaration's digest and target are verified, but the declaration alone does not prove backup existence or completeness. Operators granting deletion must separately verify and retain Git bundles, LFS, issues, settings and other required backups. - -Validation used local fixtures. Live Crowsi enrollment, authority adoption and create/push/delete acceptance tests remain unperformed. Publishing this repository does not activate these runtime operations. - -## License - -Apache-2.0; see LICENSE and NOTICE. Previously granted permissions and third-party terms remain effective. Private registration, credentials and runtime state are excluded. Generated `.tgz` archives are excluded from source and distribution. - -## Package integration +## Documentation and source -The package is an independently consumable unit. Callers reference its documented -interface through a versioned dependency and own application-specific composition -and integration. +[Interface reference](docs/interface-reference.md) -## Package publication templates +[Usage guide](docs/getting-started.md) -`templates/package-publication/` contains standalone npm and crates.io GitHub Actions templates, a public-package and archive gate, and activation policy. They are copied into each consuming repository and do not add a runtime dependency on this crate. Publishing is disabled until the registry identity, protected environment, reviewed source SHA, and package delivery prerequisites are configured. See the template policy and installation instructions in that directory. +[Examples](examples) · [Implementation and public interfaces](src) · [Verification cases](tests) · [Contributing](CONTRIBUTING.md) · [Security reporting](SECURITY.md) · [License](LICENSE) · [Attribution notices](NOTICE) diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000..408d1b0 --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,26 @@ +# Using zixcel-github + +Build and validate typed GitHub requests for repository observation and explicitly enabled operations. + +## Before you start + +A caller supplies the authenticated transport and allowed operation configuration. Creation and deletion require explicit permission for the exact target. + +## First steps + +Run from the repository root: + +```sh +cargo test --locked +``` + +## How to assess the result + +- Describe reads and supported repository changes. +- Validate request scope and parse provider results. + +A passing source-level check establishes only what that check observes. Keep missing configuration, unavailable services and unverified deployment paths visible. + +## Continue reading + +[Repository overview](../README.md) diff --git a/docs/interface-reference.md b/docs/interface-reference.md new file mode 100644 index 0000000..516fa3d --- /dev/null +++ b/docs/interface-reference.md @@ -0,0 +1,29 @@ +# zixcel-github interface reference + +Use the [usage guide](getting-started.md) for the first steps. This reference preserves the current interface details and operational limits. Run command examples from the repository root, after preparing the exact declared dependencies and registered configuration. + +## Local policy and synchronization + +`allowed_actions` is the local write ceiling. Missing or empty lists allow reads only. `ConnectorConfig::authorize_request` matches connection, organization and repository. Signed upstream grants and GitHub permissions remain separate requirements. + +```sh +cargo run -- check-configured-request examples/write-config.toml examples/create-request.json +``` + +`execute_configured_request` validates configuration before invoking the backend. Production Crowsi transport applies the same checks in verify and execute. `execute_api_request` is a lower-level typed port; callers must apply authorization and local ceilings. + +`create-private-repository`, `push-repository-snapshot` and `delete-repository` are independent permissions. Deletion requires `github-repository-administration/delete-resource`, an expected repository ID and a backup-declaration SHA-256. + +`zixcel-repository-security prepare-snapshot` prepares a checked complete-source artifact. References use `sha256:<64hex>`; digest fields use bare 64-character hex. Store `<64hex>.json` in Crowsi's artifact store. Hash the current remote commit SHA string using SHA-256 and use the bare digest in `expected_remote: {state: exact, commit_sha256: ...}`. Reobserve after changes. Force updates are never used. + +Creation distinguishes users and organizations; organizations use `/orgs/{owner}/repos`. Because Git Data API cannot operate on an empty repository, creation initializes a commit; observe its head before pushing a complete snapshot. Creation and synchronization are separate signed operations. Snapshots do not transfer local Git history. History-preserving pushes require Crowsi Git transport and separate history inspection. + +## Deletion backup declaration + +```json +{"schema":"zixcel://github/deletion-backup/v1","repository_id":"12345","owner":"example-org","repository":"example-api","bundle_digest_sha256":"sha256:<64hex>"} +``` + +The declaration's digest and target are verified, but the declaration alone does not prove backup existence or completeness. Operators granting deletion must separately verify and retain Git bundles, LFS, issues, settings and other required backups. + +Validation used local fixtures. Live Crowsi enrollment, authority adoption and create/push/delete acceptance tests remain unperformed. Publishing this repository does not activate these runtime operations.