@sun-asterisk/sungen 3.1.1 → 3.1.2-beta.100

package/README.md

@@ -1,431 +1,7 @@
-# Sungen v2 — Deterministic E2E Test Compiler
+# @sun-asterisk/sungen
 
-**Version**: 2.2.3
-**Gherkin + Selector YAML + Test Data → Playwright .spec.ts**
+Deterministic E2E test compiler — Gherkin + selector YAML + test-data → Playwright tests, with a Capability Planner and a Harness/audit layer.
 
----
+This is the **core kernel**: Gherkin→intent IR, the selector contract, the harness/audit + planner, the CLI, and the **capability SPI** that drivers plug into. It embeds no test runtime — UI, DB, and API capabilities ship as separate `@sungen/driver-*` packages discovered at runtime.
 
-## What is Sungen?
-
-Sungen is a deterministic compiler that converts Gherkin features into Playwright tests.
-
-**v2 architecture**: AI generates the input files (Gherkin + selectors), sungen compiles to tests. No AI inside sungen itself.
-
-```
-AI (Copilot/Claude + MCP Playwright) → visits URL → generates files
-sungen generate → compiles .feature + selectors.yaml + data.yaml → .spec.ts
-```
-
----
-
-## Quick Start
-
-```bash
-# Install
-npm install -g @sun-asterisk/sungen@latest
-
-# Initialize project (creates AI rules + directory structure)
-sungen init --base-url https://your-app.com
-
-# Use AI slash commands to generate tests
-# In GitHub Copilot Chat:
-/sungen-add-screen login /auth/login
-/sungen-create-test login
-/sungen-run-test login
-```
-
----
-
-## Generate from Figma (web-only, no desktop)
-
-Use a Figma design URL as the source for screen specs and test scaffolding — no live app needed.
-
-### Quick start (5 steps)
-
-```bash
-# 1. Authenticate once — stores PAT in .env (gitignored)
-sungen figma auth set
-
-# 2. Scaffold screen from a Figma frame URL
-sungen add --screen my-screen --figma "https://www.figma.com/design/<key>/<name>?node-id=<id>"
-
-# 3. Generate test cases (AI reads spec_figma.md + ui/*.png)
-# /sungen:create-test my-screen
-
-# 4. Review syntax and coverage
-# /sungen:review my-screen
-
-# 5. Generate selectors + compile + run (no live page needed for compilation)
-# /sungen:run-test my-screen
-```
-
-### PAT setup
-
-1. Go to **figma.com → Settings → Security → Personal access tokens**
-2. Click **Generate new token**
-3. Set scopes: `file_content:read`, `file_metadata:read`
-4. Copy the token — it is shown once
-5. Run `sungen figma auth set` and paste when prompted
-
-### Figma URL format
-
-```
-https://www.figma.com/design/<fileKey>/<fileName>?node-id=<nodeId>
-```
-
-Example:
-```
-https://www.figma.com/design/AbCdEfGhIjKlMnOpQrSt/My-App?node-id=1-23
-```
-
-The `node-id` selects a specific frame or component. Right-click any frame in Figma → "Copy link to selection" to get the correct URL.
-
-### Flags
-
-| Flag | Default | Description |
-|------|---------|-------------|
-| `--refresh` | false | Re-fetch image even if cached |
-| `--scale <n>` | 2 | Export resolution multiplier (1–4) |
-| `--hi-res` | false | Alias for `--scale 4` |
-
-### Cache
-
-Rendered PNGs are cached in `.sungen/figma-cache/` (gitignored). On re-run, cached images are used unless `--refresh` is passed. Cache entries are keyed by file version — a new Figma publish busts the cache automatically.
-
-### Migration notes
-
-Existing screens are unaffected. To add Figma specs to an existing screen:
-
-```bash
-sungen add --screen <existing-screen> --figma <figma-url>
-```
-
-This adds `spec_figma.md` + `requirements/ui/*.png` without touching `spec.md` or `.feature` files (idempotent).
-
-### Troubleshooting
-
-| Error | Cause | Fix |
-|-------|-------|-----|
-| `401 Unauthorized` | PAT invalid or expired | Re-run `sungen figma auth set` |
-| `403 Forbidden` | No access to file | Request access from file owner in Figma |
-| `429 Too Many Requests` | Rate limited | Automatic exponential backoff; wait and retry |
-| Expired S3 URL | Image URL expired (~30 days) | Re-run `sungen add --figma` — PNGs are downloaded locally so this is rare |
-
----
-
-## CLI Commands
-
-| Command | Description |
-|---------|-------------|
-| `sungen init` | Scaffold project + generate AI rules |
-| `sungen add --screen <name> --path <path>` | Create screen with empty templates |
-| `sungen add --screen <name> --figma <url>` | Scaffold from Figma frame (alternative to `--path`) |
-| `sungen add --screen <name> --feature <name>` | Add feature file to existing screen |
-| `sungen generate --screen <name>` | Compile Gherkin → Playwright .spec.ts |
-| `sungen generate --all` | Compile all screens |
-| `sungen makeauth <role>` | Capture browser auth state (SSO support) |
-| `sungen figma auth set` | Store Figma PAT (one-time setup) |
-| `sungen figma auth check` | Verify PAT is stored and valid |
-| `sungen figma auth clear` | Remove stored PAT |
-
----
-
-## AI Slash Commands
-
-| Action | GitHub Copilot (VS Code) | Claude Code |
-|--------|--------------------------|-------------|
-| Add screen | `/sungen-add-screen login /auth/login` | `/sungen:add-screen login /auth/login` |
-| Create test cases | `/sungen-create-test login` | `/sungen:create-test login` |
-| Compile & run tests | `/sungen-run-test login` | `/sungen:run-test login` |
-
-### create-test — Create test cases
-
-AI acts as a **Senior QA Engineer**. Supports 3 input modes:
-- **Live page** — AI visits the page via MCP Playwright, analyzes UI elements
-- **Figma / screenshots** — AI generates tests from static designs
-- **Update mode** — AI detects existing tests and asks: add new, expand, or replace
-
-Output: `.feature` + `test-data.yaml` (no selectors — those are generated during run-test)
-
-### run-test — Compile & run
-
-AI acts as a **Senior Developer**:
-1. Explores live page → generates `selectors.yaml`
-2. Compiles: `sungen generate --screen <name>`
-3. Runs: `npx playwright test`
-4. If fail → auto-fixes selectors/test-data → retry (up to 5 attempts)
-
----
-
-## Workflow
-
-### 1. Add a screen
-
-```bash
-sungen add --screen awards --path /awards
-```
-
-Creates:
-```
-qa/screens/awards/
-├── features/awards.feature      # Gherkin template
-├── selectors/awards.yaml        # Selector YAML (page entry pre-filled)
-└── test-data/awards.yaml        # Test data (empty)
-```
-
-### 2. AI generates Gherkin + selectors
-
-Use your AI assistant (GitHub Copilot or Claude Code) with MCP Playwright to:
-1. Navigate to the page URL
-2. Take an accessibility snapshot
-3. Generate `.feature` + `selectors.yaml` + `test-data.yaml`
-
-The AI rules in `.github/prompts/` and `.claude/` (created by `sungen init`) teach the AI the correct syntax.
-
-### 3. Compile + run
-
-```bash
-sungen generate --screen awards
-npx playwright test
-```
-
-### 4. Fix failures (AI verify loop)
-
-When tests fail → AI reads error → fixes `selectors.yaml` → recompile → re-run.
-
-| Error | Fix in selectors.yaml |
-|---|---|
-| strict mode: resolved to N elements | Add `exact: true` or `scope` or `nth` |
-| element(s) not found | Fix `name`, `type`, or `value` |
-| getByText matched too many | Add `match: 'exact'` or `nth` |
-
----
-
-## Gherkin Syntax
-
-**Pattern**: `[Keyword] User <Action> [Target Name] <Target Type> <with {{Value}}> <is State>`
-
-- `[Target]` → selector reference → lookup in `selectors/*.yaml`
-- `{{Value}}` → test data reference → lookup in `test-data/*.yaml`
-
-### Example
-
-```gherkin
-@feature_auth
-Feature: Login Screen
-  Path: /auth/login
-
-  @auto @smoke
-  Scenario: User logs in successfully
-    Given User is on [Login] page
-    When User fill [Email] field with {{valid_email}}
-    And User fill [Password] field with {{valid_password}}
-    And User click [Login] button
-    Then User see [Dashboard] page
-    And User see [Welcome] heading with {{success_message}}
-    And User see [Logout] button is enabled
-```
-
----
-
-## Pattern Shapes (18 categories)
-
-### Actions
-
-| Pattern | Example |
-|---|---|
-| Simple click | `User click [Submit] button` |
-| Click dynamic list | `User click [Order] row with {{order_name}}` |
-| Fill field | `User fill [Email] field with {{email}}` |
-| Fill search | `User fill [Global] search with {{keyword}}` |
-| Check/Uncheck | `User check [Remember me] checkbox` / `User check [Notification] toggle` |
-| Select dropdown | `User select [Country] dropdown with {{country}}` |
-| Upload file | `User upload [Avatar] uploader with {{path}}` |
-| Double click | `User double click [Cell] element` |
-| Hover | `User hover [Info] icon` / `User hover [Order] row` |
-| Clear | `User clear [Search] field` |
-
-> **click + with rule**: `with {{Value}}` only for dynamic lists (`row`, `item`, `card`, `option`). Never for static elements (`button`, `link`, `icon`, `tab`).
-
-### Browser Alert
-
-| Pattern | Example |
-|---|---|
-| Accept | `User click [OK] alert` (also: Accept, Yes, Confirm) |
-| Dismiss | `User click [Cancel] alert` (also: Dismiss, No) |
-| Fill prompt | `User fill [Name] alert with {{value}}` |
-
-> Alert steps must appear **before** the triggering action. Generates `page.once('dialog', ...)`.
-
-### Keyboard
-
-| Pattern | Example |
-|---|---|
-| Global key | `User press Escape key` |
-| Key on element | `User press Enter on [Search] field` |
-
-### Navigation
-
-| Pattern | Example |
-|---|---|
-| Open page | `User is on [Login] page` |
-| See page (URL) | `User see [Dashboard] page` |
-
-### Wait
-
-| Pattern | Example |
-|---|---|
-| Wait timeout | `User wait for 3 seconds` |
-| Wait element | `User wait for [Modal] dialog` |
-| Wait hidden | `User wait for [Loading] spinner is hidden` |
-| Wait with data | `User wait for [Dialog] dialog with {{title}}` |
-
-### Assertions (7 verify patterns)
-
-| Pattern | Assertion | Example |
-|---|---|---|
-| Visibility | `toBeVisible()` | `User see [Success] message` |
-| Hidden | `toBeHidden()` | `User see [Ads] modal is hidden` |
-| Text content | `toHaveText()` | `User see [Error] message with {{err_msg}}` |
-| Input value | `toHaveValue()` | `User see [Email] field with {{user_email}}` |
-| Partial text | `toContainText()` | `User see [Title] text contains {{partial}}` |
-| Component state | `toBeDisabled()` etc. | `User see [Submit] button is disabled` |
-| Page context | `toHaveURL()` | `User see [Dashboard] page` |
-
-**States**: `hidden`, `visible`, `disabled`, `enabled`, `checked`, `unchecked`, `focused`, `empty`, `loading`, `selected`, `sorted ascending`, `sorted descending`
-
-### Table
-
-| Pattern | Example |
-|---|---|
-| Column exists | `User see [Email] column in [Users] table` |
-| Row exists | `User see [Username] row in [Users] table with {{name}}` |
-| Row hidden | `User see [Username] row in [Users] table with {{name}} is hidden` |
-| Row count | `User see [Users] table with {{count}}` |
-| Empty table | `User see [Users] table is empty` |
-| Cell value | `User see [Status] column with {{status}}` (row scoped) |
-| Action in row | `User click [Edit] button in [Users] table with {{name}}` |
-
-### Scope
-
-| Pattern | Example |
-|---|---|
-| Scroll | `User scroll to [Footer] section` |
-| Frame enter | `User switch to [Payment] frame` |
-| Frame exit | `User switch to [main] frame` |
-
-### Element Types
-
-| Group | Types |
-|---|---|
-| **Context** | `page` `dialog` `modal` `drawer` `tab` `alert` `overlay` `step` |
-| **Input** | `field` `textarea` `search` `dropdown` `option` `checkbox` `radio` `toggle` `uploader` `slider` `date-picker` |
-| **Trigger** | `button` `link` `icon` `menuitem` `tag` |
-| **Data** | `table` `row` `column` `cell` `list` `item` `card` `section` |
-| **Feedback** | `message` `header` `label` `text` `tooltip` `badge` `breadcrumb` `image` |
-| **System** | `key` `frame` `spinner` `progressbar` |
-
----
-
-## Selector YAML v2 — NFC Key Format
-
-Sungen v2 uses **Unicode NFC normalization** for selector keys — not dot notation. Keys use spaces, support Vietnamese, Japanese, and all Unicode characters.
-
-```yaml
-# NFC keys (spaces, not dots)
-email address:
-  type: 'role'
-  value: 'textbox'
-  name: 'Email Address'
-  exact: true
-
-# Japanese
-ログイン:
-  type: 'role'
-  value: 'button'
-  name: 'ログイン'
-
-# Page navigation
-login:
-  type: 'page'
-  value: '/auth/login'
-
-# Scoped element
-header login:
-  type: 'role'
-  value: 'button'
-  name: 'Login'
-  scope: 'main navigation'
-```
-
-**Locator priority**: `data-testid` > `role+name` > `label` > `text` > `CSS`
-
-**Types**: `testid`, `role`, `text`, `label`, `placeholder`, `locator`, `page`, `upload`, `frame`
-
----
-
-## Tags
-
-| Tag | Level | Description |
-|-----|-------|-------------|
-| `@auto` | Scenario | Standard scenario, ready for automation |
-| `@manual` | Scenario | Skip in generation |
-| `@smoke` / `@regression` | Scenario | Test suite grouping |
-| `@auth:<role>` | Feature/Scenario | Use Playwright auth storage state |
-| `@no-auth` | Scenario | Disable inherited auth |
-| `@steps:<name>` | Scenario | Mark as reusable step block (base scenario) |
-| `@extend:<name>` | Scenario | Prepend Given→When from `@steps` block (skip Then) |
-
-**Auth precedence**: Scenario > Feature > None
-
-### Reusable Steps
-
-```gherkin
-@auth:user @steps:open-dialog
-Scenario: Open kudos dialog
-  Given User is on [kudo] page
-  When User click [Notifications] button
-  And User click [Write Kudos] menuitem
-  Then User see [panel] dialog with {{kudo_title}}
-
-@auth:user @extend:open-dialog
-Scenario: User sends a thank you message
-  Given User is on [panel] dialog with {{kudo_title}}
-  When User fill [Search] field with {{teammate_name}}
-  And User click [Send] button
-  Then User see [panel] dialog with {{kudo_title}} is hidden
-```
-
----
-
-## Project Structure
-
-```
-qa/screens/<name>/
-├── features/         # Gherkin .feature files
-├── selectors/        # Element selector YAML mappings
-└── test-data/        # Test data YAML values
-
-specs/generated/<name>/
-└── <feature>.spec.ts # Generated Playwright tests
-```
-
----
-
-## Documentation
-
-Full documentation at **[sungen.sun-asterisk.vn](https://sungen.sun-asterisk.vn)**
-
-- **[Installation Guide](https://sun-asterisk.github.io/sungen/docs/guides/installation)** — Windows (Git Bash + VS Code + Copilot), macOS, Linux
-- **[Quick Start](https://sun-asterisk.github.io/sungen/docs/guides/quick-start)** — From zero to running tests
-- **[Selector YAML Guide](https://sun-asterisk.github.io/sungen/docs/guides/selector-override)** — NFC keys, auto-infer, Japanese/Vietnamese support
-- **[Tips & Troubleshooting](https://sun-asterisk.github.io/sungen/docs/guides/tips)** — When AI gets stuck fixing tests
-- **[Gherkin Patterns](https://sun-asterisk.github.io/sungen/docs/gherkin/patterns)** — Full grammar, all patterns, compiler rules
-
----
-
-## License
-
-MIT License - see LICENSE file for details.
-
-**Made with ❤️ by eqe team (engineer & quality) — Sun Asterisk**
+See the project README and docs site for usage.

package/dist/capabilities/builtins.d.ts

@@ -0,0 +1,31 @@
+/**
+ * In-core capability registrations (Capability SPI).
+ *
+ * `ui` has moved to `@sungen/driver-ui` (R5.4); `db` and `api` still register from here via
+ * `LOCAL_DRIVERS` (they relocate in R5.5/R5.6), and `core` (the generic expect/lint/verification
+ * layer) always stays in core. Discovery (`discover.ts`) loads the external driver(s) first, then
+ * these, then `core` — preserving the historical pattern composition order, so compiled output is
+ * byte-identical (golden + audit snapshots are the proof).
+ */
+import type { CapabilityRegistry } from './registry';
+/**
+ * core — generic, capability-agnostic steps (data-vs-data `expect`) + the advisory @cases/@query
+ * lint and the gate-level `verification` sensor. Stays in core (not a driver) — the always-present
+ * generic layer. All three real capabilities (ui/db/api) now ship as `@sungen/driver-*` packages.
+ */
+export declare function registerCoreCapability(registry: CapabilityRegistry): void;
+/**
+ * In-core driver manifest — now empty: `ui`, `db`, and `api` all ship as `@sungen/driver-*` packages
+ * loaded by discovery (`discover.ts`). Kept (empty) as the seam for any future in-core capability;
+ * `core` itself registers separately via `registerCoreCapability`.
+ */
+export declare const LOCAL_DRIVERS: ReadonlyArray<{
+    capability: string;
+    register: (r: CapabilityRegistry) => void;
+}>;
+/**
+ * @deprecated Use `discoverAndRegisterCapabilities()` from `./discover`. Kept as a thin alias so
+ * existing call-sites/tests don't break during R5; removed once everything routes through discovery.
+ */
+export declare function registerBuiltinCapabilities(): void;
+//# sourceMappingURL=builtins.d.ts.map

package/dist/capabilities/builtins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../../src/capabilities/builtins.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAgDrD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,kBAAkB,GAAG,IAAI,CAMzE;AAED;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,aAAa,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,CAAC,CAAC,EAAE,kBAAkB,KAAK,IAAI,CAAA;CAAE,CAAM,CAAC;AAElH;;;GAGG;AACH,wBAAgB,2BAA2B,IAAI,IAAI,CAGlD"}

package/dist/capabilities/builtins.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOCAL_DRIVERS = void 0;
+exports.registerCoreCapability = registerCoreCapability;
+exports.registerBuiltinCapabilities = registerBuiltinCapabilities;
+const data_driven_lint_1 = require("../harness/data-driven-lint");
+const query_catalog_1 = require("../harness/query-catalog");
+const expect_patterns_1 = require("../generators/test-generator/patterns/expect-patterns");
+/** Advisory @cases/@query lint, exposed through the Sensor SPI (generate-time). */
+const dataDrivenLintSensor = {
+    id: 'data-driven-lint',
+    capability: 'core',
+    kind: 'advisory',
+    run: ({ dir, cwd }) => (0, data_driven_lint_1.lintDataDriven)(dir, cwd).map((w) => ({
+        sensorId: 'data-driven-lint',
+        capability: 'core',
+        scenario: w.scenario,
+        message: w.message,
+        severity: 'warn',
+    })),
+};
+/**
+ * Generic `verification` gate sensor: every referenced named query (`@query`) must resolve in its
+ * catalog, and the catalog must lint clean. An unresolved/invalid reference is a gate-level error.
+ * (On a project with no `@query` refs it yields nothing.) `query-catalog` lives in core's harness —
+ * shared with the data-driven advisory lint. The `@api` counterpart now lives in
+ * `@sungen/driver-api`'s `api-verification` gate sensor. Message prefix unchanged → audit byte-identical.
+ */
+const verificationGateSensor = {
+    id: 'verification',
+    capability: 'core',
+    kind: 'gate',
+    run: ({ screenName, scenarios, cwd }) => {
+        const findings = [];
+        const fail = (msg) => findings.push({ sensorId: 'verification', capability: 'core', message: `VERIFICATION-FAIL: ${msg}`, severity: 'error' });
+        const queryRefs = new Set();
+        for (const s of scenarios)
+            for (const r of s.queryRefs ?? [])
+                queryRefs.add(r);
+        for (const name of queryRefs) {
+            try {
+                (0, query_catalog_1.resolveQuery)(name, screenName, cwd);
+            }
+            catch (e) {
+                fail(e?.message || `query "${name}" does not resolve`);
+            }
+        }
+        if (queryRefs.size) {
+            try {
+                for (const err of (0, query_catalog_1.lintCatalog)(screenName, null, cwd).errors)
+                    fail(err);
+            }
+            catch { /* no catalog */ }
+        }
+        return findings;
+    },
+};
+/**
+ * core — generic, capability-agnostic steps (data-vs-data `expect`) + the advisory @cases/@query
+ * lint and the gate-level `verification` sensor. Stays in core (not a driver) — the always-present
+ * generic layer. All three real capabilities (ui/db/api) now ship as `@sungen/driver-*` packages.
+ */
+function registerCoreCapability(registry) {
+    registry.register({
+        id: 'core',
+        patterns: [...expect_patterns_1.expectPatterns],
+        sensors: [dataDrivenLintSensor, verificationGateSensor],
+    });
+}
+/**
+ * In-core driver manifest — now empty: `ui`, `db`, and `api` all ship as `@sungen/driver-*` packages
+ * loaded by discovery (`discover.ts`). Kept (empty) as the seam for any future in-core capability;
+ * `core` itself registers separately via `registerCoreCapability`.
+ */
+exports.LOCAL_DRIVERS = [];
+/**
+ * @deprecated Use `discoverAndRegisterCapabilities()` from `./discover`. Kept as a thin alias so
+ * existing call-sites/tests don't break during R5; removed once everything routes through discovery.
+ */
+function registerBuiltinCapabilities() {
+    // Lazy import avoids a cycle (discover imports builtins).
+    require('./discover').discoverAndRegisterCapabilities();
+}
+//# sourceMappingURL=builtins.js.map

package/dist/capabilities/builtins.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtins.js","sourceRoot":"","sources":["../../src/capabilities/builtins.ts"],"names":[],"mappings":";;;AA8DA,wDAMC;AAaD,kEAGC;AAzED,kEAA6D;AAC7D,4DAAqE;AACrE,2FAAuF;AAEvF,mFAAmF;AACnF,MAAM,oBAAoB,GAA8B;IACtD,EAAE,EAAE,kBAAkB;IACtB,UAAU,EAAE,MAAM;IAClB,IAAI,EAAE,UAAU;IAChB,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE,EAAE,CACpB,IAAA,iCAAc,EAAC,GAAG,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACnC,QAAQ,EAAE,kBAAkB;QAC5B,UAAU,EAAE,MAAM;QAClB,QAAQ,EAAE,CAAC,CAAC,QAAQ;QACpB,OAAO,EAAE,CAAC,CAAC,OAAO;QAClB,QAAQ,EAAE,MAAe;KAC1B,CAAC,CAAC;CACN,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,sBAAsB,GAAsB;IAChD,EAAE,EAAE,cAAc;IAClB,UAAU,EAAE,MAAM;IAClB,IAAI,EAAE,MAAM;IACZ,GAAG,EAAE,CAAC,EAAE,UAAU,EAAE,SAAS,EAAE,GAAG,EAAE,EAAE,EAAE;QACtC,MAAM,QAAQ,GAAG,EAA+B,CAAC;QACjD,MAAM,IAAI,GAAG,CAAC,GAAW,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,sBAAsB,GAAG,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC;QAEvJ,MAAM,SAAS,GAAG,IAAI,GAAG,EAAU,CAAC;QACpC,KAAK,MAAM,CAAC,IAAI,SAAS;YAAE,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,IAAI,EAAE;gBAAE,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAC/E,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;YAC7B,IAAI,CAAC;gBAAC,IAAA,4BAAY,EAAC,IAAI,EAAE,UAAU,EAAE,GAAG,CAAC,CAAC;YAAC,CAAC;YAAC,OAAO,CAAM,EAAE,CAAC;gBAAC,IAAI,CAAC,CAAC,EAAE,OAAO,IAAI,UAAU,IAAI,oBAAoB,CAAC,CAAC;YAAC,CAAC;QACzH,CAAC;QACD,IAAI,SAAS,CAAC,IAAI,EAAE,CAAC;YACnB,IAAI,CAAC;gBAAC,KAAK,MAAM,GAAG,IAAI,IAAA,2BAAW,EAAC,UAAU,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC,MAAM;oBAAE,IAAI,CAAC,GAAG,CAAC,CAAC;YAAC,CAAC;YAAC,MAAM,CAAC,CAAC,gBAAgB,CAAC,CAAC;QAC5G,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;CACF,CAAC;AAEF;;;;GAIG;AACH,SAAgB,sBAAsB,CAAC,QAA4B;IACjE,QAAQ,CAAC,QAAQ,CAAC;QAChB,EAAE,EAAE,MAAM;QACV,QAAQ,EAAE,CAAC,GAAG,gCAAc,CAAC;QAC7B,OAAO,EAAE,CAAC,oBAAoB,EAAE,sBAAsB,CAAC;KACxD,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACU,QAAA,aAAa,GAAqF,EAAE,CAAC;AAElH;;;GAGG;AACH,SAAgB,2BAA2B;IACzC,0DAA0D;IAC1D,OAAO,CAAC,YAAY,CAAC,CAAC,+BAA+B,EAAE,CAAC;AAC1D,CAAC"}

package/dist/capabilities/context-router.d.ts

@@ -0,0 +1,34 @@
+export interface RouteTask {
+    /** What is being worked on now. */
+    target: {
+        kind: string;
+        id: string;
+    };
+    /** What artifact is being produced/checked: 'feature' | 'scenario' | 'selectors' | 'apis.yaml' | … */
+    artifact: string;
+    /** Capability tags present on the target (e.g. ['@query'], ['@api'], ['@cases']). */
+    tags?: string[];
+}
+export interface RoutePlan {
+    /** Applicable capability ids: the default/implicit one + any whose annotations match the tags. */
+    capabilities: string[];
+    /** Gate sensors to run for this task (ids). */
+    gateSensorIds: string[];
+    /** Advisory sensors to run for this task (ids). */
+    advisorySensorIds: string[];
+    /** Scope: the target slice + a token/context budget (null = unbounded for now). */
+    scope: {
+        target: RouteTask['target'];
+        budget: number | null;
+    };
+}
+declare class ContextRouter {
+    /** Which capabilities a set of tags activates: the default capability + any owning a present tag. */
+    capabilitiesFor(tags?: string[]): string[];
+    /** Compute the routing plan for a task (deterministic). */
+    route(task: RouteTask): RoutePlan;
+}
+/** Process-wide singleton. */
+export declare const contextRouter: ContextRouter;
+export {};
+//# sourceMappingURL=context-router.d.ts.map

package/dist/capabilities/context-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-router.d.ts","sourceRoot":"","sources":["../../src/capabilities/context-router.ts"],"names":[],"mappings":"AAeA,MAAM,WAAW,SAAS;IACxB,mCAAmC;IACnC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;IACrC,sGAAsG;IACtG,QAAQ,EAAE,MAAM,CAAC;IACjB,qFAAqF;IACrF,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,SAAS;IACxB,kGAAkG;IAClG,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,+CAA+C;IAC/C,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,mDAAmD;IACnD,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,mFAAmF;IACnF,KAAK,EAAE;QAAE,MAAM,EAAE,SAAS,CAAC,QAAQ,CAAC,CAAC;QAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;CAC/D;AAED,cAAM,aAAa;IACjB,qGAAqG;IACrG,eAAe,CAAC,IAAI,GAAE,MAAM,EAAO,GAAG,MAAM,EAAE;IAU9C,2DAA2D;IAC3D,KAAK,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS;CAclC;AAED,8BAA8B;AAC9B,eAAO,MAAM,aAAa,eAAsB,CAAC"}

package/dist/capabilities/context-router.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.contextRouter = void 0;
+/**
+ * ContextRouter (Capability SPI, R1 — skeleton).
+ *
+ * The overload guard: for each unit of work it decides the minimal slice of Context + the relevant
+ * capabilities + the gate to load, so a project with many drivers doesn't gather everything for
+ * every artifact (cost scales by *target*, not *repo × drivers*). See
+ * `docs/spec/sungen_capability_spi_spec.md` §5.
+ *
+ * R1 scope (skeleton, deterministic, not yet enforced in the pipeline): it computes the routing
+ * plan — which capabilities apply (the default/implicit one + any whose annotation tags appear),
+ * and which sensors gate the task. Scope-trimming/token-budget enforcement is wired in a later step;
+ * for now `scope.budget` is a placeholder (null = unbounded) and the plan is advisory.
+ */
+const registry_1 = require("./registry");
+class ContextRouter {
+    /** Which capabilities a set of tags activates: the default capability + any owning a present tag. */
+    capabilitiesFor(tags = []) {
+        const ids = new Set();
+        const def = registry_1.capabilityRegistry.defaultCapabilityId();
+        if (def)
+            ids.add(def);
+        for (const cap of registry_1.capabilityRegistry.all()) {
+            if ((cap.annotations ?? []).some((a) => tags.includes(a)))
+                ids.add(cap.id);
+        }
+        return [...ids];
+    }
+    /** Compute the routing plan for a task (deterministic). */
+    route(task) {
+        const capabilities = this.capabilitiesFor(task.tags ?? []);
+        // Generic sensors (no capability, or the always-on `core`) run regardless of the task's tags;
+        // capability-specific sensors run only when their capability is in scope.
+        const inScope = (capId) => capId == null || capId === 'core' || capabilities.includes(capId);
+        const gateSensorIds = registry_1.capabilityRegistry.sensors('gate').filter((s) => inScope(s.capability)).map((s) => s.id);
+        const advisorySensorIds = registry_1.capabilityRegistry.sensors('advisory').filter((s) => inScope(s.capability)).map((s) => s.id);
+        return {
+            capabilities,
+            gateSensorIds,
+            advisorySensorIds,
+            scope: { target: task.target, budget: null },
+        };
+    }
+}
+/** Process-wide singleton. */
+exports.contextRouter = new ContextRouter();
+//# sourceMappingURL=context-router.js.map

package/dist/capabilities/context-router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-router.js","sourceRoot":"","sources":["../../src/capabilities/context-router.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;GAYG;AACH,yCAAgD;AAsBhD,MAAM,aAAa;IACjB,qGAAqG;IACrG,eAAe,CAAC,OAAiB,EAAE;QACjC,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAC;QAC9B,MAAM,GAAG,GAAG,6BAAkB,CAAC,mBAAmB,EAAE,CAAC;QACrD,IAAI,GAAG;YAAE,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACtB,KAAK,MAAM,GAAG,IAAI,6BAAkB,CAAC,GAAG,EAAE,EAAE,CAAC;YAC3C,IAAI,CAAC,GAAG,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;gBAAE,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC7E,CAAC;QACD,OAAO,CAAC,GAAG,GAAG,CAAC,CAAC;IAClB,CAAC;IAED,2DAA2D;IAC3D,KAAK,CAAC,IAAe;QACnB,MAAM,YAAY,GAAG,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;QAC3D,8FAA8F;QAC9F,0EAA0E;QAC1E,MAAM,OAAO,GAAG,CAAC,KAAc,EAAE,EAAE,CAAC,KAAK,IAAI,IAAI,IAAI,KAAK,KAAK,MAAM,IAAI,YAAY,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QACtG,MAAM,aAAa,GAAG,6BAAkB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAC/G,MAAM,iBAAiB,GAAG,6BAAkB,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACvH,OAAO;YACL,YAAY;YACZ,aAAa;YACb,iBAAiB;YACjB,KAAK,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE;SAC7C,CAAC;IACJ,CAAC;CACF;AAED,8BAA8B;AACjB,QAAA,aAAa,GAAG,IAAI,aAAa,EAAE,CAAC"}