108 lines
3.9 KiB
Markdown
108 lines
3.9 KiB
Markdown
# Standalone SDK Audit
|
|
|
|
Date: 2026-06-07
|
|
|
|
This repository is intended to be a standalone HiveCast SDK repository. The SDK
|
|
packages must be usable without the HiveCast application monorepo, without
|
|
Matrix-3 path assumptions, and without platform-only concepts such as Device
|
|
Link, Host Link, system-auth, or gateway internals.
|
|
|
|
## Current Result
|
|
|
|
The SDK package surface is standalone enough for the current authoring proof:
|
|
|
|
- A fresh consumer installs the SDK CLI as a package-manager dependency.
|
|
- `matrix init` creates a fresh author package.
|
|
- `matrix add actor` creates an actor importing `@open-matrix/core`.
|
|
- `matrix configure` writes package-local `.matrix` credentials/config.
|
|
- `matrix run` starts the actor directly.
|
|
- `matrix invoke` calls the actor through the SDK CLI.
|
|
- The generated package can be packed, installed into a separate consumer, run,
|
|
and invoked again.
|
|
|
|
The proof script also checks that generated author-package files do not contain
|
|
legacy monorepo paths or upper-layer package dependencies.
|
|
|
|
Checked-in demos now cover the same boundary in user-facing form:
|
|
|
|
- `pnpm demo:standalone` runs `examples/standalone-greeter` without provider
|
|
credentials.
|
|
- `pnpm demo:hivecast-login` validates a user-supplied HiveCast API key and
|
|
writes package-local SDK config/credentials in a temporary demo home.
|
|
|
|
## Cleanup Completed
|
|
|
|
- Root README now describes this as a provider-neutral SDK, not a HiveCast
|
|
application shard.
|
|
- Core package README and metadata use `@open-matrix/*` names and this repo URL.
|
|
- Browser host strings describe generic managed HTTP/broker surfaces instead of
|
|
HiveCast-specific local/dev URLs.
|
|
- CLI contracts describe standalone SDK boundaries and optional managed-host
|
|
integration without naming product-only packages as part of the SDK.
|
|
- The SDK CLI UAT proof no longer defaults to a HiveCast binary or
|
|
`dev.hivecast.ai`; managed-host proof requires explicit
|
|
`MATRIX_SDK_RUNTIME_HOST_BIN`.
|
|
- The internal theme manifest uses `@open-matrix/theme`.
|
|
|
|
## Intentional Guard Strings
|
|
|
|
Some upper-layer names remain only as forbidden-token checks inside proof
|
|
scripts. They are not dependencies, defaults, or runtime integration points.
|
|
They fail the proof if a generated SDK author package leaks those names.
|
|
|
|
Examples:
|
|
|
|
- `hivecast`
|
|
- `projects/matrix-3`
|
|
- `matrix-work-harness`
|
|
- `@matrix/mx-cli`
|
|
|
|
## Remaining Structural Debt
|
|
|
|
The repo still contains extraction residue that should be cleaned in the next
|
|
repo-hygiene slice:
|
|
|
|
- Top-level `src/` is an Omega source tree used by `@open-matrix/omega-core`
|
|
through relative imports.
|
|
- `packages/oracle/` is not part of the current SDK workspace packages, but it
|
|
remains in the repository and some top-level Omega files reference it.
|
|
- Some non-workspace Omega/oracle files reference `@open-matrix/inference`.
|
|
Those are not part of the current SDK authoring proof, but they are not clean
|
|
standalone SDK shape.
|
|
- `packages/omega-core/build.mjs` still emits declarations from the broad Omega
|
|
tree with `--skipLibCheck` because the extraction has not yet been narrowed to
|
|
package-local source only.
|
|
|
|
The next cleanup should copy the exact Omega subset used by
|
|
`@open-matrix/omega-core` into that package (or an explicit sibling package),
|
|
switch imports to package-local paths, remove the broad root `src/` dependency
|
|
from the build, and archive or extract oracle-specific code outside the SDK
|
|
repo surface.
|
|
|
|
## Verification Commands
|
|
|
|
Run from the repository root:
|
|
|
|
```bash
|
|
pnpm prove:cli-uat
|
|
pnpm prove
|
|
```
|
|
|
|
Expected:
|
|
|
|
- `prove:cli-uat` reports `ok: true`.
|
|
- `legacyMonorepoPathReferences` is `false`.
|
|
- `managedHostProof` is skipped unless `MATRIX_SDK_RUNTIME_HOST_BIN` is supplied.
|
|
- `prove` builds, tests, type-checks, and packs all workspace packages.
|
|
|
|
Demo checks:
|
|
|
|
```bash
|
|
pnpm demo:standalone
|
|
pnpm demo:hivecast-login -- --check
|
|
```
|
|
|
|
`demo:hivecast-login -- --check` proves the demo wiring without requiring a
|
|
secret. A real HiveCast proof requires `MATRIX_API_KEY`, `MATRIX_CLOUD`, and
|
|
`MATRIX_SPACE` from the user.
|