Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 19 additions & 63 deletions .github/workflows/sbom-provenance.yml
Original file line number Diff line number Diff line change
Expand Up @@ -123,50 +123,6 @@ jobs:
echo "components=$JSON" >> "$GITHUB_OUTPUT"
echo "Selected components: $JSON"

test-web-readiness:
needs: detect-components
if: contains(needs.detect-components.outputs.components, 'web')
runs-on: ubuntu-latest
timeout-minutes: 10
strategy:
fail-fast: false
matrix:
readiness-scenario: [healthy, database-degraded, database-timeout, horizon-degraded, horizon-timeout, dependencies-unavailable, mixed-dependency-timeout]
env:
TZ: UTC
steps:
- name: Harden Runner
uses: step-security/harden-runner@v2
with:
egress-policy: audit

- name: Checkout
uses: actions/checkout@v4
with:
persist-credentials: false

- name: Setup pnpm
uses: pnpm/action-setup@v4
with:
version: 10.0.0

- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: 20
cache: pnpm

- name: Install dependencies
run: |
cd ${{ github.workspace }}
pnpm install --frozen-lockfile

- name: Run web tests (readiness/liveness focus)
run: pnpm --dir web exec vitest run src/app/api/health/health.test.ts
env:
READINESS_SCENARIO: ${{ matrix.readiness-scenario }}
MOCK_CLOCK_ISO: "2024-01-01T00:00:00.000Z"

generate-sdk:
needs: detect-components
if: contains(needs.detect-components.outputs.components, 'sdk')
Expand Down Expand Up @@ -268,7 +224,7 @@ jobs:
}

echo "cdx-json=${BASE}.cdx.json" >> "$GITHUB_OUTPUT"
echo "cdx-name=talos-sdk-${GITHUB_REF_NAME:-$SHA}-$TS" >> "$GITHUB_OUTPUT"
echo "cdx-name=talos-sdk-${SHA}-$TS" >> "$GITHUB_OUTPUT"

- name: Validate CycloneDX SBOM
shell: bash
Expand Down Expand Up @@ -456,7 +412,7 @@ jobs:
builder: { id: 'https://github.com/actions/runner/github-hosted' },
metadata: {
invocationId: '${{ github.run_id }}-${{ github.run_attempt }}',
startedOn: '${{ github.event.head_commit.timestamp || new Date().toISOString() }}',
startedOn: new Date().toISOString(),
completedOn: new Date().toISOString()
}
}
Expand All @@ -471,9 +427,9 @@ jobs:
shell: bash
run: |
SHA="${GITHUB_SHA:0:7}"
echo "cyclonedx-artifact=sbom-sdk-cyclonedx-${GITHUB_REF_NAME:-$SHA}" >> "$GITHUB_OUTPUT"
echo "spdx-artifact=sbom-sdk-spdx-${GITHUB_REF_NAME:-$SHA}" >> "$GITHUB_OUTPUT"
echo "signature-artifact=sbom-sdk-signatures-${GITHUB_REF_NAME:-$SHA}" >> "$GITHUB_OUTPUT"
echo "cyclonedx-artifact=sbom-sdk-cyclonedx-${SHA}" >> "$GITHUB_OUTPUT"
echo "spdx-artifact=sbom-sdk-spdx-${SHA}" >> "$GITHUB_OUTPUT"
echo "signature-artifact=sbom-sdk-signatures-${SHA}" >> "$GITHUB_OUTPUT"

- name: Upload CycloneDX SBOM
uses: actions/upload-artifact@v4
Expand Down Expand Up @@ -605,7 +561,7 @@ jobs:
}

echo "cdx-json=${BASE}.cdx.json" >> "$GITHUB_OUTPUT"
echo "cdx-name=talos-agent-${GITHUB_REF_NAME:-$SHA}-$TS" >> "$GITHUB_OUTPUT"
echo "cdx-name=talos-agent-${SHA}-$TS" >> "$GITHUB_OUTPUT"

- name: Generate SPDX SBOM
id: spdx
Expand Down Expand Up @@ -731,9 +687,9 @@ jobs:
shell: bash
run: |
SHA="${GITHUB_SHA:0:7}"
echo "cyclonedx-artifact=sbom-agent-cyclonedx-${GITHUB_REF_NAME:-$SHA}" >> "$GITHUB_OUTPUT"
echo "spdx-artifact=sbom-agent-spdx-${GITHUB_REF_NAME:-$SHA}" >> "$GITHUB_OUTPUT"
echo "signature-artifact=sbom-agent-signatures-${GITHUB_REF_NAME:-$SHA}" >> "$GITHUB_OUTPUT"
echo "cyclonedx-artifact=sbom-agent-cyclonedx-${SHA}" >> "$GITHUB_OUTPUT"
echo "spdx-artifact=sbom-agent-spdx-${SHA}" >> "$GITHUB_OUTPUT"
echo "signature-artifact=sbom-agent-signatures-${SHA}" >> "$GITHUB_OUTPUT"

- name: Upload CycloneDX
uses: actions/upload-artifact@v4
Expand Down Expand Up @@ -860,7 +816,7 @@ jobs:
fi

echo "cdx-json=${BASE}.cdx.json" >> "$GITHUB_OUTPUT"
echo "cdx-name=talos-contracts-${GITHUB_REF_NAME:-$SHA}-$TS" >> "$GITHUB_OUTPUT"
echo "cdx-name=talos-contracts-${SHA}-$TS" >> "$GITHUB_OUTPUT"

- name: Generate SPDX SBOM
id: spdx
Expand Down Expand Up @@ -968,7 +924,7 @@ jobs:
];
const wasms=fs.readdirSync('contracts/target/wasm32-unknown-unknown/release').filter(f=>f.endsWith('.wasm'));
for (const w of wasms) subjects.push({name:w,digest:{sha256:sha256('contracts/target/wasm32-unknown-unknown/release/'+w)}});
const pred={'_type':'https://in-toto.io/Statement/v1',subject,
const pred={'_type':'https://in-toto.io/Statement/v1',subject: subjects,
predicateType:'https://slsa.dev/provenance/v1',
predicate:{buildDefinition:{
buildType:'https://github.com/slsa-framework/slsa-github-generator/generic@v1',
Expand All @@ -986,9 +942,9 @@ jobs:
shell: bash
run: |
SHA="${GITHUB_SHA:0:7}"
echo "cyclonedx-artifact=sbom-contracts-cyclonedx-${GITHUB_REF_NAME:-$SHA}" >> "$GITHUB_OUTPUT"
echo "spdx-artifact=sbom-contracts-spdx-${GITHUB_REF_NAME:-$SHA}" >> "$GITHUB_OUTPUT"
echo "signature-artifact=sbom-contracts-signatures-${GITHUB_REF_NAME:-$SHA}" >> "$GITHUB_OUTPUT"
echo "cyclonedx-artifact=sbom-contracts-cyclonedx-${SHA}" >> "$GITHUB_OUTPUT"
echo "spdx-artifact=sbom-contracts-spdx-${SHA}" >> "$GITHUB_OUTPUT"
echo "signature-artifact=sbom-contracts-signatures-${SHA}" >> "$GITHUB_OUTPUT"

- name: Upload CycloneDX
uses: actions/upload-artifact@v4
Expand Down Expand Up @@ -1110,7 +1066,7 @@ jobs:
"
}
echo "cdx-json=${BASE}.cdx.json" >> "$GITHUB_OUTPUT"
echo "cdx-name=talos-web-${GITHUB_REF_NAME:-$SHA}-$TS" >> "$GITHUB_OUTPUT"
echo "cdx-name=talos-web-${SHA}-$TS" >> "$GITHUB_OUTPUT"

- name: Generate SPDX SBOM
id: spdx
Expand Down Expand Up @@ -1214,9 +1170,9 @@ jobs:
shell: bash
run: |
SHA="${GITHUB_SHA:0:7}"
echo "cyclonedx-artifact=sbom-web-cyclonedx-${GITHUB_REF_NAME:-$SHA}" >> "$GITHUB_OUTPUT"
echo "spdx-artifact=sbom-web-spdx-${GITHUB_REF_NAME:-$SHA}" >> "$GITHUB_OUTPUT"
echo "signature-artifact=sbom-web-signatures-${GITHUB_REF_NAME:-$SHA}" >> "$GITHUB_OUTPUT"
echo "cyclonedx-artifact=sbom-web-cyclonedx-${SHA}" >> "$GITHUB_OUTPUT"
echo "spdx-artifact=sbom-web-spdx-${SHA}" >> "$GITHUB_OUTPUT"
echo "signature-artifact=sbom-web-signatures-${SHA}" >> "$GITHUB_OUTPUT"

- name: Upload CycloneDX
uses: actions/upload-artifact@v4
Expand Down Expand Up @@ -1291,7 +1247,7 @@ jobs:
echo "| Component | CycloneDX | SPDX | Provenance | Signatures |" >> "$GITHUB_STEP_SUMMARY"
echo "|-----------|-----------|------|------------|------------|" >> "$GITHUB_STEP_SUMMARY"
for comp in sdk agent contracts web; do
res="SKIPPED"
need="generate-$comp"
case "$comp" in
sdk) res="${{ needs.generate-sdk.result }}" ;;
agent) res="${{ needs.generate-agent.result }}" ;;
Expand Down
155 changes: 1 addition & 154 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -202,159 +202,6 @@ If you are iterating on contract behavior, also run the Wasm-target test path us
cargo test --target wasm32-unknown-unknown
```

## Focused Test Selection and CI Triage

Run the smallest test set that covers the files you touched before falling back to a full suite. The commands below avoid database resets and hidden local state. Run them after installing dependencies with `pnpm install` at the repository root, `uv sync --extra dev` in `packages/prime-agent/`, or the Rust setup from the prerequisites. In this section, commands that call package scripts use `pnpm run <script>` so the script name can be checked directly in the package's `package.json`.

### Web changes

Use the web package scripts for Next.js, API, database, and DevX changes. The main test artifact is the Vitest report in stdout. Benchmark jobs also upload `.benchmarks/` as the `benchmark-artifacts` workflow artifact.

```bash
# POSIX shells
pnpm --dir web exec vitest run tests/health.test.ts
pnpm --dir web exec vitest run tests/*.unit.test.ts
pnpm --dir web exec vitest run tests/openapi-snapshot.test.ts
pnpm --dir web exec vitest run src/area/devx/__tests__/runner.test.ts
pnpm --dir web run lint
pnpm --dir web exec tsc --noEmit
```

```powershell
# Windows PowerShell
pnpm --dir web exec vitest run tests\health.test.ts
pnpm --dir web exec vitest run tests\*.unit.test.ts
pnpm --dir web exec vitest run tests/openapi-snapshot.test.ts
pnpm --dir web exec vitest run src/area/devx/__tests__/runner.test.ts
pnpm --dir web run lint
pnpm --dir web exec tsc --noEmit
```

Choose the focused command by area:

| Changed files | Focused command | CI workflow |
| --- | --- | --- |
| `web/src/app/api/**`, `web/src/lib/openapi.ts`, `web/tests/fixtures/openapi.snapshot.json` | `pnpm --dir web exec vitest run tests/openapi-snapshot.test.ts` | `Web OpenAPI CI` |
| `web/drizzle/**`, `web/src/db/**`, `web/drizzle.config.ts` | `pnpm --dir web run db:migrate`, then the specific DB test with `pnpm --dir web exec vitest run tests/<name>.test.ts` | `Web Migrations CI` |
| `web/src/area/devx/**` | `pnpm --dir web exec vitest run src/area/devx/__tests__/runner.test.ts` | `Benchmark CI - regression gates` |
| API route or library unit tests | `pnpm --dir web exec vitest run tests/<name>.test.ts` | `Deploy Web -> Vercel` |
| Backup or restore paths | `pnpm --dir web exec vitest run tests/backup-crypto.test.ts tests/backup-types.test.ts` | `Web Backups CI` |

Use `pnpm --dir web run test:e2e` only when API route behavior depends on the running app or cross-route state. Use the local stack with `pnpm stack:up` when you need Postgres plus the mock Stellar provider, and clean it up with `pnpm stack:down`. Do not use `pnpm stack:reset` unless you intentionally want to destroy and recreate local stack data.

### SDK changes

The TypeScript SDK lives in `packages/sdk/`. The expected build artifact is `packages/sdk/dist/`, including the browser bundle at `packages/sdk/dist/browser/sdk.bundle.js`.

```bash
# POSIX shells
pnpm --filter @talos-protocol/sdk exec vitest run tests/client.test.ts
pnpm --filter @talos-protocol/sdk run build
pnpm --filter @talos-protocol/sdk exec tsc --noEmit
```

```powershell
# Windows PowerShell
pnpm --filter @talos-protocol/sdk exec vitest run tests\client.test.ts
pnpm --filter @talos-protocol/sdk run build
pnpm --filter @talos-protocol/sdk exec tsc --noEmit
```

Choose the focused command by area:

| Changed files | Focused command | CI workflow |
| --- | --- | --- |
| `packages/sdk/src/**`, `packages/sdk/tests/**` | `pnpm --filter @talos-protocol/sdk exec vitest run tests/<name>.test.ts` | `SDK Compatibility Tests` |
| `packages/sdk/src/generated-types.ts`, `web/tests/fixtures/openapi.snapshot.json` | `pnpm --filter @talos-protocol/sdk run build`, then verify `git diff` | `SDK Types CI` |
| SDK build, packaging, or browser bundle files | `pnpm --filter @talos-protocol/sdk run build` | `SDK Compatibility Tests` |

If `SDK Compatibility Tests` reports a missing `compat:*` script, check `.github/workflows/sdk-compatibility.yml` and `packages/sdk/package.json` together. The workflow invokes smoke-test script names, while the package manifest is the source of available local scripts.

### Prime Agent changes

The Python agent uses `uv` from `packages/prime-agent/`. The expected artifacts are pytest and ruff output in the CI log.

```bash
# POSIX shells
cd packages/prime-agent
uv run pytest tests/test_scheduler.py -v
uv run pytest tests/ -v
uv run ruff check src tests
```

```powershell
# Windows PowerShell
Set-Location packages\prime-agent
uv run pytest tests\test_scheduler.py -v
uv run pytest tests\ -v
uv run ruff check src tests
Set-Location ..\..
```

Choose the focused command by area:

| Changed files | Focused command | CI workflow |
| --- | --- | --- |
| `packages/prime-agent/src/talos_agent/scheduler.py` | `uv run pytest tests/test_scheduler.py -v` | `Prime Agent CI` |
| `packages/prime-agent/src/talos_agent/backup_service.py`, `packages/prime-agent/tests/test_backup_service.py` | `uv run pytest tests/test_backup_service.py -v` | `Web Backups CI`, `Prime Agent CI` |
| Any other agent module | `uv run pytest tests/test_<area>.py -v`, plus `uv run ruff check src tests` | `Prime Agent CI` |

Some integration tests need external credentials or services such as Stellar, browser adapters, social adapters, or AI providers. If a failure is caused by a missing environment variable or refused network connection, document it as environment-dependent in your PR instead of replacing it with a broad unrelated suite.

### Contract changes

The Soroban contracts live in `contracts/`. The expected build artifacts are Wasm files under `contracts/target/wasm32-unknown-unknown/release/`.

```bash
# POSIX shells
cd contracts
cargo test -p talos-registry
cargo test
cargo build --target wasm32-unknown-unknown --release
pnpm --dir contracts exec tsc --noEmit
pnpm --dir contracts exec vitest run fixtures
```

```powershell
# Windows PowerShell
Set-Location contracts
cargo test -p talos-registry
cargo test
cargo build --target wasm32-unknown-unknown --release
pnpm --dir contracts exec tsc --noEmit
pnpm --dir contracts exec vitest run fixtures
Set-Location ..
```

Choose the focused command by area:

| Changed files | Focused command | CI workflow |
| --- | --- | --- |
| `contracts/talos_registry/**` | `cargo test -p talos-registry` | `Contracts CI` |
| `contracts/talos_name_service/**` | `cargo test -p talos-name-service` | `Contracts CI` |
| `contracts/talos_governance/**` | `cargo test -p talos-governance` | `Contracts CI` |
| `contracts/ttl_manager/**` | `cargo test -p ttl-manager` | `Contracts CI` |
| `contracts/storage_migration/**` | `cargo test -p storage-migration` | `Contracts CI` |
| `contracts/fixtures/**` | `pnpm --dir contracts exec tsc --noEmit; pnpm --dir contracts exec vitest run fixtures` | `Contracts CI` |
| Contract release output or Wasm compatibility | `cargo build --target wasm32-unknown-unknown --release` | `Contracts CI` |

Deploy commands such as `pnpm --dir contracts run deploy:testnet` and `./deploy.sh testnet` require configured Stellar credentials and network access. Treat failures from missing signers, RPC timeouts, Horizon rate limits, or Soroban testnet availability as deployment-environment issues unless local `cargo test` or Wasm build also fails.

### Common failure messages

| Message | Usually means | Next step |
| --- | --- | --- |
| `ERR_PNPM_OUTDATED_LOCKFILE` or frozen lockfile failures | `package.json` and lockfile are out of sync | Re-run the same install command locally and commit lockfile changes only when dependency changes are intentional. |
| `No test files found` | The path or glob does not match from the package working directory | Re-run from the package root or use `pnpm --dir <package> exec vitest run <path>`. |
| `DATABASE_URL` or `DIRECT_URL` is missing | The command needs a Postgres-backed environment | Copy `web/.env.example` to `web/.env.local` or use `pnpm stack:up` for local integration work. |
| `ECONNREFUSED`, `ENOTFOUND`, Horizon/RPC timeout, or preview URL missing | External service, local server, mock provider, or Vercel preview is unavailable | Check the named workflow logs first. If local unit tests pass and only the external service failed, note it as environment-dependent. |
| `schema.ts is out of sync with committed migration files` | Drizzle schema and migrations diverged | Run `pnpm --dir web run db:generate`, inspect the generated SQL, and commit it only when the schema change is intended. |
| `Generated types differ from committed version` | OpenAPI snapshot and SDK generated types drifted | Run the repository's generated-type workflow and review `packages/sdk/src/generated-types.ts`. |
| `Browser bundle not built` or missing `packages/sdk/dist/browser/sdk.bundle.js` | SDK build did not produce the expected browser artifact | Run `pnpm --filter @talos-protocol/sdk run build:browser` or the full SDK build. |
| `ruff` violations | Python formatting or lint rule failures | Run `uv run ruff check src tests` in `packages/prime-agent/` and fix the reported files. |
| `wasm32-unknown-unknown` target not installed | Rust cannot build Soroban Wasm artifacts | Run `rustup target add wasm32-unknown-unknown`. |
| PR preview comment is present but Vercel URL is absent | The repo preview workflow provisions the mock DB; Vercel attaches previews separately | Check Vercel's GitHub integration/status before treating it as an application failure. |

## Code Style

- Keep changes small and focused
Expand Down Expand Up @@ -524,7 +371,7 @@ pnpm --dir web env:provision 123 my-feature-branch
# Teardown the mock environment
pnpm --dir web env:teardown 123
```
Unit tests for the environment lifecycle logic reside in `web/src/area/devx/__tests__/environments.test.ts` (or similar tests). Make sure tests pass locally by running the relevant Vitest file directly, for example `pnpm --dir web exec vitest run src/area/devx/__tests__/environments.test.ts`.
Unit tests for the environment lifecycle logic reside in `web/src/area/devx/__tests__/environments.test.ts` (or similar tests). Make sure tests pass locally by running `pnpm --dir web test:bench` or your standard test suites.

### Rollback and Teardown

Expand Down
1 change: 1 addition & 0 deletions contracts/Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

33 changes: 0 additions & 33 deletions contracts/fixtures/event-query.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -312,36 +312,3 @@ describe("malformed payloads", () => {
).toThrow(UnknownEventError);
});
});

describe("malformed-fixture failure-path check", () => {
it("rejects fixture set with missing format", () => {
const bad = { ...raw };
delete (bad as any).format;
expect(() => parseFixtureSet(bad)).toThrow(MalformedEventError);
});

it("rejects fixture set with invalid bounds min/max page size", () => {
const bad = {
...raw,
bounds: {
min_page_size: 10,
max_page_size: 5,
max_ledger_span: 100,
},
};
expect(() => parseFixtureSet(bad)).toThrow(MalformedEventError);
});

it("rejects an invalid event fixture with mismatched topic[0] symbol value", () => {
const badFixture = {
id: "bad.mismatched_symbol",
family: "creation",
event: "tls_crt",
contract: "talos_registry",
ledger_sequence: 100,
topics: [{ type: "symbol", value: "wrong_symbol_name" }],
data: [],
};
expect(() => parseEventFixture(badFixture, set)).toThrow(MalformedEventError);
});
});
2 changes: 1 addition & 1 deletion contracts/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
"deploy:name-service:testnet": "soroban contract deploy --wasm target/wasm32-unknown-unknown/release/talos_name_service.wasm --network testnet",
"invoke:registry": "soroban contract invoke --source-account alice --network testnet",
"invoke:name-service": "soroban contract invoke --source-account alice --network testnet",
"test:fixtures": "tsc --noEmit && vitest run fixtures"
"test:fixtures": "vitest run fixtures"
},
"devDependencies": {
"typescript": "^5.7.0",
Expand Down
Loading