chore: import upstream snapshot with attribution
This commit is contained in:
wehub-resource-sync
@@ -0,0 +1,73 @@
|
||||
---
|
||||
name: insforge-dev
|
||||
description: Use this skill set when contributing to the InsForge monorepo itself. This is for InsForge maintainers and contributors editing the platform, the shared dashboard package, the self-hosting shell, the UI library, shared schemas, tests, or docs.
|
||||
---
|
||||
|
||||
# InsForge Dev
|
||||
|
||||
Use this skill set for work inside the InsForge repository.
|
||||
|
||||
Then use the narrowest package skill that matches the task:
|
||||
|
||||
- `backend`
|
||||
- `dashboard`
|
||||
- `ui`
|
||||
- `shared-schemas`
|
||||
- `docs`
|
||||
|
||||
Use the cross-repo release workflow skill when preparing an OSS PR:
|
||||
|
||||
- `e2e-testing`
|
||||
|
||||
## Core Rules
|
||||
|
||||
1. Identify the package boundary before editing.
|
||||
- `backend/`: API, auth, database, providers, realtime, schedules
|
||||
- `packages/dashboard/`: publishable dashboard package that supports `self-hosting` and `cloud-hosting` modes
|
||||
- `frontend/`: local React + Vite shell that mounts `packages/dashboard/` in `self-hosting` mode
|
||||
- `packages/shared-schemas/`: cross-package contracts
|
||||
- `packages/ui/`: reusable design-system primitives
|
||||
- `docs/`: product and agent-facing documentation
|
||||
|
||||
2. Put code in the narrowest correct layer.
|
||||
- Contract change: `packages/shared-schemas/` first, then consumers.
|
||||
- Backend behavior: route -> service -> provider/infra.
|
||||
- Shared dashboard behavior, routes, features, exports, and host contracts: `packages/dashboard/`.
|
||||
- Self-hosting-only bootstrap, env wiring, and shell styling: `frontend/`.
|
||||
- Reusable primitive: `packages/ui/` first.
|
||||
|
||||
3. Preserve repo conventions.
|
||||
- Backend TS source uses ESM-style `.js` import specifiers.
|
||||
- Backend success responses usually return raw JSON, not `{ data }`.
|
||||
- Backend validation commonly uses shared Zod schemas plus `AppError`.
|
||||
- Dashboard data access goes through `apiClient` and React Query.
|
||||
- Dashboard frontend tests are split into Vitest unit tests, Vitest component tests, and Playwright UI smoke tests.
|
||||
- Shared payloads belong in `@insforge/shared-schemas`.
|
||||
- Never use the TypeScript `any` type. Prefer precise types, schema-derived types, `unknown`, or generics.
|
||||
|
||||
4. Do not confuse repo development with app development on InsForge.
|
||||
- This repo contains the platform, the publishable dashboard package, and a local shell for self-hosting mode.
|
||||
- Keep guidance focused on maintaining InsForge itself.
|
||||
|
||||
## Finish Rules
|
||||
|
||||
- Run the smallest validation that gives confidence for the change.
|
||||
- Use repo-level checks like `npm run lint`, `npm run build`, `npm run typecheck`, and `npm test` when the change crosses package boundaries — each is wired through Turborepo (`turbo run <task>`) and covers every workspace, including `packages/dashboard/` and `packages/shared-schemas/`.
|
||||
- For dashboard UI behavior changes, choose the lowest useful frontend test layer from the `dashboard` skill and run that command before reporting back.
|
||||
- Use the package-specific validation steps in the child skill when the work is isolated to one package.
|
||||
- When reporting back, state what changed, what you validated, and what you could not validate.
|
||||
|
||||
## Pre-PR Checklist (Mandatory Before Pushing to a PR)
|
||||
|
||||
Before opening a PR or pushing new commits to an existing PR branch, run **all** of the following from the repo root and do not proceed while any of them fail on files your change touches:
|
||||
|
||||
1. `npx turbo run typecheck` — must pass across all packages.
|
||||
2. `npx turbo run lint` — must pass. If the failure is pre-existing in `main` and unrelated to your change, scope it:
|
||||
- Run `npx eslint <your-changed-files>` and confirm your files are clean.
|
||||
- Call out the pre-existing debt in the PR body so reviewers know it is not yours.
|
||||
- Auto-fixable prettier/eslint errors in your own diff must be fixed (`npx eslint --fix <file>` or `npm run format`).
|
||||
3. `npx turbo run test` (or the package-specific test command) — all tests must pass, including any new tests you added for the change.
|
||||
4. `npx turbo run build` if routing, config, schemas, or cross-package exports changed.
|
||||
5. Use `e2e-testing` to run the deterministic cross-repo E2E gate before opening, updating, or submitting the InsForge OSS PR.
|
||||
|
||||
Never push with failing checks on files you touched, even if CI would catch them later. CI failures slow reviewers down and the lint fix almost always takes less than a minute locally.
|
||||
@@ -0,0 +1,74 @@
|
||||
---
|
||||
name: backend
|
||||
description: Use this skill when contributing to InsForge's backend package. This is for maintainers editing backend routes, services, providers, auth, database logic (including RLS-enforced surfaces like storage and realtime), schedules, or backend tests in the InsForge monorepo.
|
||||
---
|
||||
|
||||
# InsForge Dev Backend
|
||||
|
||||
Use this skill for `backend/` work in the InsForge repository.
|
||||
|
||||
## Scope
|
||||
|
||||
- `backend/src/api/**`
|
||||
- `backend/src/services/**`
|
||||
- `backend/src/providers/**`
|
||||
- `backend/src/infra/**`
|
||||
- `backend/tests/**`
|
||||
|
||||
## Working Rules
|
||||
|
||||
1. Keep the route -> service -> provider/infra split intact.
|
||||
- Routes handle auth, parsing, validation, and delegation.
|
||||
- Services own business logic and orchestration.
|
||||
- Providers and infra wrap external systems or lower-level integrations.
|
||||
- Service layer code should be the only layer that interacts with the core PostgreSQL database.
|
||||
- Do not put direct database access in routes.
|
||||
- Do not bypass services when reading from or writing to Postgres.
|
||||
|
||||
2. Follow backend conventions.
|
||||
- Use ESM-style `.js` import specifiers in TypeScript source.
|
||||
- InsForge's core database is PostgreSQL.
|
||||
- InsForge currently runs as a single-instance server, so be careful about introducing logic that assumes distributed coordination, cross-instance locking, or background worker separation.
|
||||
- Reuse shared schemas from `@insforge/shared-schemas` when contracts cross packages.
|
||||
- Use `safeParse` plus `AppError` for invalid input.
|
||||
- Return successful results through `successResponse`.
|
||||
- Preserve existing auth middleware patterns such as `verifyAdmin`, `verifyUser`, and `verifyApiKey`.
|
||||
- Never use the TypeScript `any` type. Prefer precise interfaces, schema-derived types, `unknown`, or constrained generics.
|
||||
- For schema changes, write a new migration file instead of editing database structure manually.
|
||||
- Put schema changes under `backend/src/infra/database/migrations/`.
|
||||
|
||||
3. Write idempotent migrations. Every SQL migration must be safe to re-run.
|
||||
- Use `CREATE TABLE IF NOT EXISTS`, `CREATE INDEX IF NOT EXISTS`, `ADD COLUMN IF NOT EXISTS`.
|
||||
- Never use bare `ALTER TABLE ... RENAME TO` — it fails if the target name already exists. Wrap renames in a `DO` block that checks `information_schema.tables` for both source and target.
|
||||
- Always `DROP TRIGGER IF EXISTS` before `CREATE TRIGGER`.
|
||||
- Guard data migrations and `DROP COLUMN` behind `information_schema.columns` checks when the column may already be gone.
|
||||
- Use `ON CONFLICT` or `WHERE NOT EXISTS` for seed `INSERT` statements.
|
||||
|
||||
4. Preserve existing behavior around mutation flows.
|
||||
- Keep audit logging when surrounding routes already log state changes.
|
||||
- Keep error handling flowing through shared middleware.
|
||||
- Do not introduce a new response envelope unless the existing feature already uses one.
|
||||
- For critical flows with multiple dependent database writes, use an explicit transactional process so the whole operation succeeds or fails together.
|
||||
- Be especially careful with transactions around auth, secrets, billing-like usage updates, schema changes, and any flow that would leave the system inconsistent if partially applied.
|
||||
|
||||
5. Use Postgres Row Level Security, not app-side filters, for tables accessed via authenticated end-user routes (anything where `req.user` reaches the service layer). RLS-enforced services such as storage, realtime, and payments should use `withUserContext`. Tables accessed only by admin or service-internal paths (audit logs, billing aggregations) don't need RLS. Do not write `WHERE user_id = $1` filters in services; let RLS evaluate `auth.jwt() ->> 'sub'` against the row.
|
||||
- Plumb identity through `withUserContext(pool, ctx, fn, settings?)` from `services/database/user-context.service.ts`. It opens a transaction, sets `SET LOCAL ROLE` plus the canonical `request.jwt.claims` JSON GUC via `set_config`, applies optional transaction-local settings such as `realtime.channel_name`, runs `fn`, commits on success or rolls back on error, and resets role in `finally` so policies see the calling user via `auth.jwt() ->> 'sub'`.
|
||||
- Keep `UserContext` user-only and defined in `api/middlewares/auth.ts`: `{ id, role, email? }` (`id` is always present at the API level). API keys and admin bypass flags do not belong inside `UserContext`.
|
||||
- Routes that issue out-of-band URLs (S3 presigned redirects, signed download links, anything the client redeems against a service that won't re-evaluate RLS) must do an explicit RLS-scoped existence check before handing the URL out — RLS does not fire when the client redeems the URL directly. See `StorageService.objectIsVisible` as the template.
|
||||
- Migrations that enable RLS on an existing populated table must auto-install a sensible default policy set so the upgrade does not silently break existing rows. See migration 036's `IF EXISTS (SELECT 1 FROM <table>) THEN <create policies> END IF` pattern.
|
||||
- When adding a new RLS-enforced table: enable RLS, `GRANT` table-level CRUD to `authenticated`, and write per-operation policies (SELECT, INSERT, UPDATE, DELETE). Public-bucket-style anonymous bypasses live at the route layer before calling the RLS helper, not in policies.
|
||||
- Normal raw SQL and custom migrations execute as `project_admin`. It has service-key row visibility, but PostgreSQL grants and ownership still limit object access and DDL.
|
||||
|
||||
6. Always write unit tests for new code.
|
||||
- Every new feature, migration, service, or bug fix should have accompanying unit tests.
|
||||
- For migrations, write tests that validate SQL structure and idempotency guards (see `tests/unit/redirect-url-whitelist-migration.test.ts` for the pattern).
|
||||
- For services, test business logic and error cases.
|
||||
- For RLS-gated services, mock the pool/client and pin the SQL sequence (see `tests/unit/user-context.service.test.ts` and `tests/unit/storage-object-is-visible.test.ts`).
|
||||
- Run the full test suite before submitting work: `cd backend && npm test`.
|
||||
|
||||
## Validation
|
||||
|
||||
- `cd backend && npm test`
|
||||
- `cd backend && npm run build`
|
||||
|
||||
For contract changes, also validate `packages/shared-schemas/` and any affected dashboard consumers.
|
||||
@@ -0,0 +1,107 @@
|
||||
---
|
||||
name: dashboard
|
||||
description: Use this skill when contributing to InsForge's shared dashboard package. This is for maintainers editing `packages/dashboard`, which ships in `self-hosting` and `cloud-hosting` modes, and the local `frontend/` shell used for `self-hosting` in this repo.
|
||||
---
|
||||
|
||||
# InsForge Dev Dashboard
|
||||
|
||||
Use this skill for dashboard work in the InsForge repository.
|
||||
|
||||
## Scope
|
||||
|
||||
- `packages/dashboard/src/**`
|
||||
- `packages/dashboard/package.json`
|
||||
- `packages/dashboard/README.md`
|
||||
- `packages/dashboard/*.config.*`
|
||||
- `frontend/src/**`
|
||||
- `frontend/package.json`
|
||||
|
||||
## Working Rules
|
||||
|
||||
1. Respect the shared-package versus host-app boundary.
|
||||
- This dashboard is built with React and TypeScript.
|
||||
- `packages/dashboard/` is the source of truth for the dashboard product.
|
||||
- The package must support both `self-hosting` and `cloud-hosting` modes.
|
||||
- Keep self-hosting-only bootstrap, local env defaults, and shell styling in `frontend/`.
|
||||
- Do not let `packages/dashboard/` depend on `frontend/`.
|
||||
- If both modes need a capability, define it in the package API first.
|
||||
|
||||
2. Preserve dashboard data-flow conventions.
|
||||
- Follow the flow `service -> hook -> UI`.
|
||||
- Use `apiClient` for HTTP calls so auth refresh and error handling stay consistent.
|
||||
- Put request logic in services, data fetching and mutation state in hooks, and rendering/orchestration in UI components and pages.
|
||||
- Reuse existing contexts, host abstractions, and hooks before creating new global state.
|
||||
|
||||
3. Reuse the existing component layers.
|
||||
- Use `@insforge/ui` for generic primitives.
|
||||
- Use shared dashboard components when the pattern is already present.
|
||||
- Keep reusable dashboard UI in `packages/dashboard/`.
|
||||
- Only add UI to `frontend/` when it is specific to the local self-hosting shell.
|
||||
- Keep package styles scoped to the dashboard container.
|
||||
|
||||
4. Keep the package surface aligned with shared contracts.
|
||||
- Import cross-package types and Zod-derived shapes from `@insforge/shared-schemas`.
|
||||
- When backend payloads change, update the related services, hooks, UI, and exported types together.
|
||||
- Keep `packages/dashboard/src/index.ts` and `packages/dashboard/src/types` aligned with the public package API.
|
||||
- Never use the TypeScript `any` type. Prefer precise prop, state, API, and hook result types.
|
||||
|
||||
## Frontend Testing
|
||||
|
||||
Use the lowest test layer that covers the risk. Add one focused regression test for bug fixes when practical.
|
||||
|
||||
| Change type | Test layer | Location | Command |
|
||||
| --- | --- | --- | --- |
|
||||
| Pure helper, parser, formatter, state reducer | Unit | `packages/dashboard/src/**/__tests__/*.test.ts` | `npm --workspace @insforge/dashboard run test:unit` |
|
||||
| React component behavior, forms, dialogs, conditional rendering | Component | `packages/dashboard/src/**/__tests__/*.test.tsx` | `npm --workspace @insforge/dashboard run test:component` |
|
||||
| Routing, auth redirects, host-mode integration, browser-only behavior | UI smoke | `packages/dashboard/tests/ui/*.spec.ts` | `npm --workspace @insforge/dashboard run test:ui` |
|
||||
|
||||
Conventions:
|
||||
|
||||
- `npm --workspace @insforge/dashboard run test` runs the full Vitest suite: unit plus component.
|
||||
- GitHub Actions splits dashboard checks into unit, component, and UI jobs in `.github/workflows/frontend-tests.yml`. Update the workflow when adding or renaming test scripts.
|
||||
- Unit tests should avoid React rendering and network mocking. Test data transformations directly.
|
||||
- Component tests use Testing Library with `packages/dashboard/src/test/setup.ts`. Mock hooks, services, and host context at the package boundary; assert user-visible behavior and callback effects, not implementation details or CSS class strings.
|
||||
- UI smoke tests use Playwright against the local `frontend/` shell. Mock backend API routes in `packages/dashboard/tests/ui/fixtures/`; every mocked route must either fulfill, fallback, or abort. Do not leave requests pending after a test branch.
|
||||
- Prefer one clear test per user-observable behavior over broad snapshot tests. Avoid brittle assertions tied to copy that is not part of the behavior being protected.
|
||||
|
||||
## Local debug: viewing cloud-hosting-only UI in self-hosting
|
||||
|
||||
**Use when** previewing UI gated on `useIsCloudHostingMode()`, `isInsForgeCloudProject()`, or a PostHog feature flag (e.g. the CTest dashboard variant, `dashboard-v3-experiment === 'c_test'`, the CLI connect panel) while running the local `frontend/` self-hosting shell.
|
||||
|
||||
The lowest-friction approach is to **temporarily hardcode** the three gates below to `true`/the new branch, then restart the Vite dev server. These edits bypass real host/project detection and MUST be fully reverted before committing — landing them breaks both self-hosting and cloud-hosting users.
|
||||
|
||||
### Hardcodes
|
||||
|
||||
1. `packages/dashboard/src/lib/config/DashboardHostContext.tsx` — `useIsCloudHostingMode()` → `return true;` (was `useDashboardHost().mode === 'cloud-hosting'`).
|
||||
2. `packages/dashboard/src/lib/utils/utils.ts` — `isInsForgeCloudProject()` → `return true;` (was the `.insforge.app` hostname check).
|
||||
3. If the UI is also feature-flag-gated, hardcode the consumer. For CTest: `AppRoutes.tsx` → `const DashboardHomePage = CTestDashboardPage;` and, if relevant, the matching branch in `AppLayout.tsx` for `<ConnectDialogV2>`.
|
||||
|
||||
Mark every hardcode with a trailing `// LOCAL DEBUG: <original expression>` comment so revert is a mechanical search.
|
||||
|
||||
### Revert checklist — run all before committing
|
||||
|
||||
1. `git grep -n "LOCAL DEBUG" packages/dashboard/src/` returns zero matches.
|
||||
2. Each gate is restored to its **original expression**, not just an equivalent value (the `mode === 'cloud-hosting'` comparison, the hostname check, the `getFeatureFlag(...)` call must all be back).
|
||||
3. Any imports deleted during debug (commonly `DashboardPage`, `getFeatureFlag`, `ConnectDialog`) are restored.
|
||||
4. `cd packages/dashboard && npm run lint && npm run typecheck` both pass.
|
||||
5. `git diff` of the four files above shows only intended changes — no `return true;`, no missing imports.
|
||||
|
||||
### Rationalizations to reject
|
||||
|
||||
| Excuse | Reality |
|
||||
|--------|---------|
|
||||
| "I'll revert in a follow-up PR." | Follow-up = a window where prod is broken. Revert now. |
|
||||
| "The original check was effectively the same." | If it were, you wouldn't have needed the hardcode. Restore the expression, not a value-equivalent. |
|
||||
| "Lint passed, so the deleted import doesn't matter." | Lint passed because the import was deleted; on revert the original code needs it back. |
|
||||
| "I'll ship the env-var override instead." | No env-var override is wired in the code. Don't invent one on the commit path — restore the original. |
|
||||
|
||||
## Validation
|
||||
|
||||
- `cd packages/dashboard && npm run test:unit` when changing pure helpers or reducers
|
||||
- `cd packages/dashboard && npm run test:component` when changing React component behavior
|
||||
- `cd packages/dashboard && npm run test:ui` when changing routing, auth, host-mode integration, or browser-only behavior
|
||||
- `cd packages/dashboard && npm run typecheck`
|
||||
- `cd packages/dashboard && npm run build`
|
||||
- `cd frontend && npm run build` when the local self-hosting shell changes
|
||||
|
||||
For shared contract changes, also validate `packages/shared-schemas/` and the affected backend surface.
|
||||
@@ -0,0 +1,47 @@
|
||||
---
|
||||
name: docs
|
||||
description: Use this skill when contributing to InsForge's product documentation in this repository. This is for maintainers editing public docs in `docs/core-concepts`, agent docs in `.agents/docs`, SDK integration guides in `docs/sdks`, and OpenAPI specs in `openapi`.
|
||||
---
|
||||
|
||||
# InsForge Dev Docs
|
||||
|
||||
Use this skill for `docs/core-concepts/`, `.agents/docs/`, `docs/sdks/`, and `openapi/` in the InsForge repository.
|
||||
|
||||
The documentation in this repo is primarily product documentation for InsForge users and agents integrating with InsForge. This skill is for InsForge engineers maintaining that public documentation surface.
|
||||
|
||||
## Scope
|
||||
|
||||
- `docs/core-concepts/**`
|
||||
- `.agents/docs/**`
|
||||
- `docs/sdks/**`
|
||||
- `openapi/**`
|
||||
|
||||
## Working Rules
|
||||
|
||||
1. Put each document in the correct documentation surface.
|
||||
- Human-friendly docs published on the public doc site belong in `docs/core-concepts/` and related public doc folders.
|
||||
- For implementation-heavy public docs, prefer an `architecture.md` file inside the relevant `docs/core-concepts/<domain>/` folder.
|
||||
- Agent-only instructions belong in `.agents/docs/`.
|
||||
- SDK integration guides for each framework belong in `docs/sdks/`.
|
||||
- OpenAPI contract changes belong in the matching files under `openapi/`.
|
||||
|
||||
2. Match the writing style to the audience.
|
||||
- Public docs should be human-friendly and explain the implementation clearly.
|
||||
- Keep public docs human-sounding: avoid AI-writing tells such as em dashes, rule-of-three lists, "not just X but Y" parallelism, inflated significance, vague attribution, and AI vocabulary (delve, leverage, underscore, seamless, robust). See the `doc-author` skill's `INSFORGE.md` overlay, "Sound human, not AI-generated".
|
||||
- `architecture.md` pages in `docs/core-concepts/` should explain how the feature works in detail.
|
||||
- Agent docs in `.agents/docs/` should be instruction-first and execution-oriented.
|
||||
- Agent docs should avoid explanatory filler and focus on the exact steps an agent should follow to complete the work.
|
||||
|
||||
3. Prevent documentation drift on every implementation change.
|
||||
- Before changing implementation, check the current user-facing docs for that feature.
|
||||
- After changing implementation, update the relevant Markdown docs and the relevant OpenAPI YAML files in the same pass.
|
||||
- Do not treat OpenAPI and Markdown as separate optional follow-ups when the feature contract or behavior changed.
|
||||
- If a change affects agent workflows, update the corresponding file in `.agents/docs/`.
|
||||
- If a change affects public product understanding, update the corresponding file in `docs/core-concepts/`, including `architecture.md` when implementation details changed.
|
||||
- If a change affects SDK integration guidance, update the corresponding framework guide in `docs/sdks/`.
|
||||
|
||||
## Validation
|
||||
|
||||
- Re-read every documented command, path, route, and payload for correctness.
|
||||
- Cross-check OpenAPI YAML and Markdown docs against the implemented behavior before finishing.
|
||||
- Mention anything you could not verify directly.
|
||||
@@ -0,0 +1,142 @@
|
||||
---
|
||||
name: e2e-testing
|
||||
description: Use this skill when an InsForge maintainer has finished an OSS repo change and is ready to open, update, or submit the InsForge PR. Runs the release-quality deterministic E2E gate by building a package.json-derived InsForge test image tag, deciding whether sibling agent-e2e fixture coverage must change, dispatching the Deterministic Fixture E2E workflow, waiting for results, and triaging failures before PR submission.
|
||||
---
|
||||
|
||||
# InsForge E2E Testing Gate
|
||||
|
||||
Use this skill after local implementation and normal InsForge pre-PR checks pass, and before opening, updating, or submitting the InsForge OSS PR.
|
||||
|
||||
This is an additional release-quality gate. It does not replace local `typecheck`, `lint`, `test`, or `build` validation from the parent `insforge-dev` skill.
|
||||
|
||||
## Repositories
|
||||
|
||||
- InsForge OSS repo: current workspace.
|
||||
- E2E repo: remote GitHub repository `InsForge/agent-e2e`.
|
||||
|
||||
Use the remote `InsForge/agent-e2e` repository for workflow dispatch and read-only workflow checks. Do not rely on a developer-specific local checkout path. Create or use a local checkout only when the deterministic fixture tests must be edited.
|
||||
|
||||
## Build The Test Tag
|
||||
|
||||
1. Read the root InsForge `package.json` version.
|
||||
2. Increment only the patch number.
|
||||
3. Build a tag in this form:
|
||||
|
||||
```text
|
||||
v<major>.<minor>.<patch+1>-<feature-or-issue-slug>
|
||||
```
|
||||
|
||||
Example: root version `2.2.3` and feature `storage returning rls` becomes `v2.2.4-storage-returning-rls`.
|
||||
|
||||
Use the `package.json` version as the only source of truth for the base version. Ignore higher existing test tags when calculating the base version.
|
||||
|
||||
Slug rules:
|
||||
|
||||
- Prefer the issue key, PR topic, or branch topic.
|
||||
- Lowercase all letters.
|
||||
- Replace runs of non-alphanumeric characters with one hyphen.
|
||||
- Trim leading and trailing hyphens.
|
||||
- Keep it short enough to scan in GitHub Actions and image tags.
|
||||
|
||||
## Build The InsForge Image
|
||||
|
||||
Dispatch the InsForge `Build and Push Docker Image` workflow with the test tag:
|
||||
|
||||
```bash
|
||||
gh workflow run "Build and Push Docker Image" --repo InsForge/InsForge --ref <insforge-feature-branch> -f test_tag=<test-tag>
|
||||
```
|
||||
|
||||
Then wait for the matching run to complete:
|
||||
|
||||
```bash
|
||||
gh run list --repo InsForge/InsForge --workflow "Build and Push Docker Image" --limit 10
|
||||
gh run watch --repo InsForge/InsForge <run-id>
|
||||
```
|
||||
|
||||
Do not start the cross-repo E2E workflow until the image build succeeds.
|
||||
|
||||
## Decide Whether `agent-e2e` Must Change
|
||||
|
||||
Inspect the InsForge diff and compare it with deterministic fixture coverage in `InsForge/agent-e2e`.
|
||||
|
||||
For read-only checks, prefer remote GitHub access such as `gh api`, `gh repo view`, or remote file reads. Use a local checkout only when editing fixture files or when remote inspection is not enough to understand coverage.
|
||||
|
||||
Update `agent-e2e` when the InsForge change adds, removes, or changes behavior that the deterministic fixture should assert, including:
|
||||
|
||||
- API contract or validation behavior.
|
||||
- Auth, permissions, RLS, storage, realtime, functions, schedules, AI, SDK, or CLI-visible behavior.
|
||||
- Any regression that local tests cover but the release gate should also protect across the deployed runtime.
|
||||
|
||||
Do not update `agent-e2e` for internal refactors, docs-only changes, local test-only changes, or behavior already covered by the deterministic fixture with no assertion change needed.
|
||||
|
||||
Ignore `Support Desk Agent E2E (Exploratory)`. It is not part of this gate.
|
||||
|
||||
## If No E2E Test Update Is Needed
|
||||
|
||||
Run the deterministic fixture workflow from `agent-e2e` main:
|
||||
|
||||
```bash
|
||||
gh workflow run "Deterministic Fixture E2E" --repo InsForge/agent-e2e --ref main -f insforge_tag=<test-tag>
|
||||
```
|
||||
|
||||
Find and watch the run:
|
||||
|
||||
```bash
|
||||
gh run list --repo InsForge/agent-e2e --workflow "Deterministic Fixture E2E" --limit 10
|
||||
gh run watch --repo InsForge/agent-e2e <run-id>
|
||||
```
|
||||
|
||||
## If E2E Tests Need An Update
|
||||
|
||||
Work in a local checkout of the remote `InsForge/agent-e2e` repo only for the fixture update.
|
||||
|
||||
1. Use an existing clean checkout or clone `https://github.com/InsForge/agent-e2e.git` into an isolated workspace.
|
||||
2. Fetch `origin` and start from `origin/main`.
|
||||
3. Create a branch named `codex/<short-topic>`.
|
||||
4. Update only the deterministic fixture validators, fixtures, app assertions, and docs needed for the InsForge behavior change.
|
||||
5. Run the smallest local validation that gives confidence:
|
||||
|
||||
```bash
|
||||
npm run typecheck
|
||||
npm run lint
|
||||
npm run fixture:e2e:dry
|
||||
```
|
||||
|
||||
Run broader validation when the changed fixture area supports it.
|
||||
|
||||
6. Open an `agent-e2e` PR for the fixture update.
|
||||
7. Dispatch the deterministic fixture workflow from the `agent-e2e` branch that contains the fixture update:
|
||||
|
||||
```bash
|
||||
gh workflow run "Deterministic Fixture E2E" --repo InsForge/agent-e2e --ref <agent-e2e-branch> -f insforge_tag=<test-tag>
|
||||
```
|
||||
|
||||
8. Watch the run before proceeding with the InsForge PR.
|
||||
|
||||
## Interpret Results
|
||||
|
||||
If the deterministic fixture workflow passes:
|
||||
|
||||
- Link the run in the InsForge PR body or final PR notes.
|
||||
- If an `agent-e2e` PR was required, link that PR too.
|
||||
- Proceed with opening, updating, or submitting the InsForge OSS PR.
|
||||
|
||||
If the deterministic fixture workflow fails:
|
||||
|
||||
1. Inspect the failed job logs and uploaded artifact.
|
||||
2. Identify whether the failure is caused by the InsForge implementation, the new or existing deterministic fixture, a transient infrastructure problem, or an unrelated existing failure.
|
||||
3. Fix the correct branch:
|
||||
- InsForge implementation bug: update the InsForge branch, rebuild the test image with the same tag or a new short retry tag, then rerun E2E.
|
||||
- Fixture bug or missing assertion update: update the `agent-e2e` branch, rerun local validation, then rerun E2E from that branch.
|
||||
- Transient infrastructure issue: rerun once after noting the evidence.
|
||||
4. Do not submit the InsForge PR until the deterministic result is clear or the user explicitly accepts the risk.
|
||||
|
||||
## Report Back
|
||||
|
||||
When finished, report:
|
||||
|
||||
- Test tag used.
|
||||
- InsForge image workflow run result.
|
||||
- Whether `agent-e2e` changed.
|
||||
- Deterministic Fixture E2E run result.
|
||||
- Links to the InsForge PR, `agent-e2e` PR if any, and workflow runs.
|
||||
@@ -0,0 +1,43 @@
|
||||
---
|
||||
name: shared-schemas
|
||||
description: Use this skill when contributing to InsForge's shared schema package. This is for maintainers editing published Zod contracts, exported types, and shared API payload definitions consumed by InsForge packages in this repo and other InsForge tooling.
|
||||
---
|
||||
|
||||
# InsForge Dev Shared Schemas
|
||||
|
||||
Use this skill for `packages/shared-schemas/` work in the InsForge repository.
|
||||
|
||||
## Scope
|
||||
|
||||
- `packages/shared-schemas/src/**`
|
||||
- any code in this repo that consumes the changed contracts
|
||||
- downstream InsForge tooling that depends on the published `@insforge/shared-schemas` package, including consumers not present in this repository
|
||||
|
||||
## Working Rules
|
||||
|
||||
1. Treat `packages/shared-schemas/` as the source of truth for cross-package payloads.
|
||||
- If a request, response, or domain shape is shared across InsForge surfaces, define it here.
|
||||
- Do not duplicate the same contract in package-local files.
|
||||
- Remember that this package is not only for the repo's backend and dashboard packages. It is also consumed by other InsForge tooling, including MCP and SDK code that may live outside this repository.
|
||||
|
||||
2. Keep schemas organized by domain.
|
||||
- Follow the existing `*.schema.ts` and `*-api.schema.ts` split when it fits the current package pattern.
|
||||
- Keep `packages/shared-schemas/src/index.ts` aligned with the intended public API.
|
||||
- Treat exported names and schema shapes as a public contract surface, not just an internal refactor target.
|
||||
|
||||
3. Use schema changes as a synchronization trigger.
|
||||
- Update backend validation and response usage.
|
||||
- Update shared dashboard services, hooks, and UI assumptions in `packages/dashboard/`.
|
||||
- Check for import sites across `packages/*`, `frontend/`, and `backend/` before finishing.
|
||||
- Call out likely downstream impact on MCP, SDK, or other external InsForge consumers when a change alters exported names, schema semantics, or payload shape.
|
||||
- Be conservative with breaking changes. If a breaking contract change is necessary, make it explicit in the handoff.
|
||||
- Never use the TypeScript `any` type. Shared contracts should stay explicit and trustworthy across package boundaries.
|
||||
|
||||
## Validation
|
||||
|
||||
- `cd packages/shared-schemas && npm run build`
|
||||
- `cd backend && npx tsc --noEmit`
|
||||
- `cd packages/dashboard && npm run typecheck`
|
||||
|
||||
Run package-specific tests as needed where behavior changed.
|
||||
If external consumers such as MCP or SDK cannot be validated from this repo, say that clearly instead of implying they were covered.
|
||||
@@ -0,0 +1,42 @@
|
||||
---
|
||||
name: ui
|
||||
description: Use this skill when contributing to InsForge's reusable UI package. This is for maintainers editing design-system primitives, exports, styles, and package-level component behavior in the InsForge monorepo.
|
||||
---
|
||||
|
||||
# InsForge Dev UI
|
||||
|
||||
Use this skill for `packages/ui/` work in the InsForge repository.
|
||||
|
||||
## Scope
|
||||
|
||||
- `packages/ui/src/components/**`
|
||||
- `packages/ui/src/lib/**`
|
||||
- `packages/ui/src/index.ts`
|
||||
- `packages/ui/src/styles.css`
|
||||
|
||||
## Working Rules
|
||||
|
||||
1. Put only reusable primitives here.
|
||||
- If the component is generic across dashboard features or other InsForge apps, it belongs in `packages/ui/`.
|
||||
- If it is tightly coupled to one dashboard workflow but should ship to both OSS and cloud hosts, keep it in `packages/dashboard/`.
|
||||
- If it is only for the self-hosting host app, keep it in `frontend/`.
|
||||
|
||||
2. Preserve the package's implementation style.
|
||||
- Use `class-variance-authority` for variants when appropriate.
|
||||
- Use the shared `cn()` helper for class merging.
|
||||
- Follow the existing Radix-wrapper and typed-export patterns.
|
||||
|
||||
3. Keep the public surface in sync.
|
||||
- Export new public components from `packages/ui/src/index.ts`.
|
||||
- Avoid adding internal-only abstractions to the package surface unless they are meant to be consumed.
|
||||
- Never use the TypeScript `any` type. Keep component props and exported helpers strictly typed.
|
||||
|
||||
4. Validate downstream impact.
|
||||
- The shared dashboard package consumes this package directly, so UI changes can break `packages/dashboard/` even if `packages/ui/` itself builds cleanly.
|
||||
|
||||
## Validation
|
||||
|
||||
- `cd packages/ui && npm run build`
|
||||
- `cd packages/ui && npm run typecheck`
|
||||
|
||||
Also validate `packages/dashboard/` when the changed component is used in the dashboard, and validate `frontend/` if the host app integration or CSS entrypoints changed.
|
||||
Reference in New Issue
Block a user