@aifabrix/builder 2.52.0 → 2.53.0

package/.cursor/rules/cli-layout.mdc

@@ -1,81 +0,0 @@
----
-description: Apply when adding or changing aifabrix CLI commands, subcommands, flags, help text, terminal output (chalk), TTY vs JSON/--json, or CLI tests. Ensures layout, glyphs, and output profiles match repo standards.
-alwaysApply: false
----
-
-# Builder CLI layout rules
-
-When you touch **CLI surface** (`bin/aifabrix.js`, `lib/cli.js`, `lib/cli/**`, `lib/commands/**`) or **shared CLI formatters**, you must keep behavior aligned with the canonical docs in this folder.
-
-**Product-neutral copy:** User-facing help, errors, and warnings must not reference internal plan IDs or hardcode lab-only integration names in generic code. See [cli-product-neutral.mdc](./cli-product-neutral.mdc).
-
-## Sources of truth (read before shipping)
-
-| Document | Role |
-| -------- | ---- |
-| [layout.md](./layout.md) | Visual and semantic spec: colors, sections, glyphs, blocking vs warning, non-TTY/CI, helper map to `cli-test-layout-chalk.js`. |
-| [cli-output-command-matrix.md](./cli-output-command-matrix.md) | **One row per leaf command**: expected **output profile** (layout-blocks, tty-summary, stream-logs, json-opt, stdout-only, delegate) and **Manifest roots (141)** (when to emit gray manifest path line — see plan 141). |
-
-If implementation and `layout.md` disagree, **fix implementation** or **update docs** in the same change so they stay one story.
-
-## Output profiles (from the matrix)
-
-Use the matrix row for your command to decide UX:
-
-- **layout-blocks** — Structured blocks (header, verdict, lists, failures). Prefer helpers from `lib/utils/cli-test-layout-chalk.js` (or `lib/utils/cli-layout-chalk.js` re-export). Respect **`--json`**: skip TTY-only layout when the command is classified **json-opt** or when JSON mode is documented for that flow.
-- **tty-summary** — Short chalk lines / tables; still use canonical glyphs and semantic colors.
-- **stream-logs** — Tail/stream style; do not force layout-blocks around raw log lines unless product asks for a wrapper.
-- **json-opt** — Human TTY layout when interactive; **machine-oriented** output when `--json` (no decorative layout).
-- **stdout-only** — Stable, script-friendly stdout; minimal chalk; often used for diffs or piping.
-- **delegate** — Output comes from delegated library (wizard, etc.); still avoid forbidden glyphs and spurious decoration in anything you add.
-
-**New leaf command:** add a row to [cli-output-command-matrix.md](./cli-output-command-matrix.md) with the correct profile combination and **Manifest roots (141)** code (`141`, `141+`, `int`, `cfg`, `—`).
-
-## Manifest path visibility (plan 141)
-
-When a command’s matrix cell is **141**, **141+**, or **int** and the implementation reads an `application.yaml` (or integration equivalent), print **one** gray metadata line for humans (e.g. `Manifest: cwd/builder — /abs/path/application.yaml`) using `metadata()` or a small helper from `cli-test-layout-chalk.js`. Do not spam per-substep. Follow [.cursor/plans/141-manifest-location.plan.md](../plans/141-manifest-location.plan.md).
-
-**`aifabrix setup`:** destructive / conflict prompts that list folders to be replaced must use **resolved absolute paths** for every directory (plan § Guided setup — not only `builder/<app>/` under an otherwise absolute builder root).
-
-From [layout.md](./layout.md) contributor appendix:
-
-| Role | Use | Do not use |
-| ---- | --- | ----------- |
-| Success | **✔** | ✓, heavy check, decorative check emoji |
-| Warning | **⚠** | ‼, random emoji |
-| Failure | **✖** | ✗, `x`, decorative X |
-| Skipped | **⏭** | — |
-| In progress | **⏳** | Hourglass as pure decoration |
-
-- **Red = blocking only** (hard failure / non-zero exit when that line is the verdict). **Yellow = non-blocking** warnings. Never use red for warnings.
-- **Non-TTY / CI** (`NO_COLOR`, chalk level 0): **same glyphs and line structure**; colors become no-ops. Do not invent a second plain-text vocabulary (e.g. `[OK]` instead of ✔) unless the command is explicitly **stdout-only machine** output.
-
-Markdown headings in `layout.md` may use emoji for doc navigation; **user-facing terminal strings** follow the semantic glyph table only.
-
-## Implementation
-
-- **Canonical helpers:** `lib/utils/cli-test-layout-chalk.js` (see symbol → helper table in [layout.md](./layout.md) § “Implementation map”).
-- **Preferred import alias:** `lib/utils/cli-layout-chalk.js` re-exports the same API when the path should not contain `test`.
-- **Prefer** `formatSuccessLine`, `formatSuccessParagraph`, `formatWarningLine`, `formatBlockingError`, `failureGlyph`, `successGlyph`, and other exported section helpers over ad hoc `` chalk.green(`✔ …`) `` for one-off success/error lines.
-- **Composite / indented lines** (e.g. `successGlyph()` + `chalk.white(…)`, or `  ✔ …` in validate-style output) may stay raw chalk **only** when a single helper would not match the spec; keep glyphs canonical.
-- **Tests:** extend or add tests under `tests/lib/utils/cli-test-layout-chalk.test.js` (and command tests) when behavior or snapshots encode layout.
-
-## Code entry points and maintenance
-
-- **Shared formatters:** `lib/utils/cli-test-layout-chalk.js` (canonical exports).
-- **Neutral re-export:** `lib/utils/cli-layout-chalk.js` → same module.
-- **Unit tests:** `tests/lib/utils/cli-test-layout-chalk.test.js`.
-
-**Optional follow-up:** If you touch centralized command error handling (e.g. `handleCommandError`), consider aligning it with `formatBlockingError` (but preserve `--json` / stdout-only behavior for script modes).
-
-## Commander and UX checklist
-
-- [ ] **Help**: `.description()` and `.option()` texts clear; default values and env overrides documented when behavior is non-obvious.
-- [ ] **Profile**: Matrix row added/updated for every new **leaf** command path.
-- [ ] **JSON / script**: If the command supports `--json` or machine output, JSON path skips TTY layout and stays stable for scripts.
-- [ ] **Errors**: Blocking failures use **✖** + red via shared helpers where possible; non-blocking issues use **⚠** + yellow.
-- [ ] **Docs**: User-facing CLI documentation lives under `docs/` per [docs-rules.mdc](./docs-rules.mdc) (command-centric; no raw HTTP/API tutorial in user docs unless that doc is explicitly contributor-focused).
-
-## Related plans
-
-Historical adoption context: `.cursor/plans/Done/129-cli_layout_adoption.plan.md`. Keep **cli-output-command-matrix.md** accurate when profiles or helper adoption change.

package/.cursor/rules/cli-product-neutral.mdc

@@ -1,43 +0,0 @@
----
-description: Apply when changing aifabrix CLI code, help text, errors, or user-facing docs under docs/commands. Keeps product output free of internal plans, training labs, and hardcoded integration names.
-alwaysApply: false
----
-
-# CLI product-neutral output (Builder)
-
-The **aifabrix** CLI is a **product**. User-visible strings must not encode internal engineering artifacts.
-
-## Forbidden in product paths
-
-Applies to **`lib/cli/**`**, **`lib/commands/**`**, CLI help (Commander `.description()` / `.option()` / `addHelpText`), **`lib/utils/*-error*.js`**, terminal messages from **`lib/utils/cli-*`**, and **`docs/commands/**`** (see [docs-rules.mdc](./docs-rules.mdc)).
-
-| Do not use | Use instead |
-| ---------- | ----------- |
-| Internal plan IDs (`Plan 331`, `plan 148`, `BK-1`) | User terms: *active datasource schema guards*, *schema replacement*, *overlap* |
-| Training / lab-only system keys baked into `if` branches (`sharepoint-e2e`, `hubspot-demo` in runtime logic) | **Dynamic** behavior from `systemKey`, `appName`, manifest, env.template, or secrets map |
-| Hardcoded vendor or connector names in generic helpers | Generic rules (path suffix, namespace, configuration keys from disk) |
-| Cursor plan file paths in errors or help | Link only in `.cursor/plans/` and contributor docs |
-
-**Examples in docs/commands** may name real apps (`hubspot-e2e`) when illustrating a command; **library code** must not special-case those names unless the user passed them as arguments.
-
-## Required patterns
-
-- **Missing `kv://` secrets:** Compare requested paths to the loaded secrets map generically (e.g. same path segment under a different namespace). Never hardcode `sharepoint` / `sharepoint-e2e` (or any other lab pair) in `lib/`.
-- **`--force` messaging:** Describe dataplane behavior (*bypass active-datasource schema replacement guards*), not internal plan numbers. Do **not** append extra CLI hints by matching English substrings on API errors — the dataplane pipeline already returns remediation in the 400 body when schema replacement is blocked.
-- **No `upload-pipeline-error-hints`-style modules:** Prefer forwarding `formatApiError` output; optional hints belong in the API contract, not duplicated heuristics in the CLI.
-- **Auth / pipeline errors:** Describe what the user can do (`aifabrix login`, `AIFABRIX_DEPLOYMENT_AUTH=client-credentials`), not ticket or plan IDs.
-- **JSDoc `@fileoverview`:** No plan numbers; optional brief behavior description only.
-
-## Verification
-
-Before merging CLI UX changes:
-
-1. `rg -i 'plan [0-9]|BK-[0-9]|sharepoint-e2e' lib/cli lib/commands lib/utils --glob '*.js'` → no matches in generic helpers (fixture strings in tests are OK).
-2. New error hints must work for **any** integration folder name the user owns.
-3. [cli-layout.mdc](./cli-layout.mdc) and [docs-rules.mdc](./docs-rules.mdc) still apply for glyphs and user-doc scope.
-
-## Related
-
-- [cli-layout.mdc](./cli-layout.mdc) — terminal layout and output profiles
-- [docs-rules.mdc](./docs-rules.mdc) — public CLI documentation audience
-- [project-rules.mdc](./project-rules.mdc) — ISO / security baseline

package/.cursor/rules/deploy-rules/docker-image-ip-policy.mdc

@@ -1,49 +0,0 @@
----
-description: Builder-api and platform app Docker image IP policy — staging, explicit COPY, content gate
-globs:
-  - builder/builder-api/Dockerfile
-  - templates/applications/builder-api/Dockerfile
-  - .dockerignore
-  - scripts/stage_builder_api_for_docker.js
-  - scripts/docker_image_content_gate.js
-  - lib/build/builder-api-docker-staging.js
-alwaysApply: false
----
-
-# Docker image IP policy (builder-api)
-
-Customer-pullable **builder-api** images must contain **runtime orchestration only**, not the full Builder CLI monorepo.
-
-## Required pattern (builder-api)
-
-1. **Deny by default** — repo-root `.dockerignore` excludes dev trees from build context.
-2. **Stage on host** — `node scripts/stage_builder_api_for_docker.js` (also via `aifabrix build builder-api`) writes `docker-builder-api-staging/`.
-3. **Explicit COPY** — `builder/builder-api/Dockerfile` copies staging output only; never `COPY lib ./lib` or `COPY . .`.
-4. **Prove it** — `node scripts/docker_image_content_gate.js <image> builder-api` must pass before ACR push.
-5. **Non-root** — container runs as `appuser` (or documented service user).
-6. **No agent ACR build** — see `acr-build-restrictions.mdc` in miso builder rules; user runs registry build/push.
-
-## SSOT files
-
-| File | Role |
-| ---- | ---- |
-| `builder/builder-api/Dockerfile` | Canonical image definition |
-| `templates/applications/builder-api/Dockerfile` | Published via `npm run sync-json` only |
-| `scripts/stage_builder_api_for_docker.js` | Runtime allowlist + manifest |
-| `scripts/docker_image_content_gate.js` | Post-build forbidden-path gate |
-| `.dockerignore` | Build context hardening |
-
-## Forbidden in builder-api images
-
-- `/app/.cursor`, `/app/builder`, `/app/integration`, `/app/tests`, `/app/docs`, `/app/scripts`, `/app/packages`
-- `/app/bin/aifabrix.js` (full CLI entry)
-- `/app/templates/*` except `templates/openapi/` and `templates/external-system/` (runtime wizard/ReDoc only)
-- `*.md` under `/app/lib/`
-
-## Dev-reload
-
-`aifabrix run builder-api --reload` bind-mounts source for local dev. Image hardening applies to **production/ACR** builds only.
-
-## When changing runtime imports
-
-If `lib/programmatic/` or its transitive requires change, re-run staging manifest tests (`tests/scripts/stage_builder_api_for_docker.test.js`) and rebuild the image gate.

package/.cursor/rules/docs-rules.mdc

@@ -1,32 +0,0 @@
----
-alwaysApply: true
----
-# Documentation Rules – CLI User Docs
-
-## Audience
-
-Documents under **docs/** (including **docs/commands/**) are **public CLI user documentation**. The audience is people who use the AI Fabrix Builder CLI or integrate it into workflows—they may **not** have access to private monorepos (dataplane, miso-controller, internal plans). They do not need to know how the CLI talks to the Controller or Dataplane over HTTP.
-
-## Do Not Include in CLI User Docs
-
-- **Links or paths into other product repos (FORBIDDEN)** – No markdown links, examples, or prerequisites that point at private/sibling repositories or their trees: `../../../aifabrix-dataplane/...`, `../../aifabrix-miso/...`, `packages/miso-controller/...`, `integration/<fixture>/README.md` in another repo, `.cursor/plans/` anywhere, `/workspace/...` monorepo layouts, or “see the dataplane/miso-controller repo”. **Only** cross-link within **`docs/`** and use on-disk paths the user owns (`integration/<systemKey>/...`, `builder/<appKey>/...`, `~/.aifabrix/...`).
-- **Internal plan or ticket IDs** – No “Plan 407.1”, “plan section 2.3”, or similar; describe behavior in user terms.
-- **REST API details** – No HTTP methods, URL paths, or endpoint names (e.g. `GET /api/v1/...`, `POST .../pipeline/upload`).
-- **Request/response shapes** – No payload structures, status codes, or field names from backend APIs.
-- **Backend implementation terms** – Avoid referring to “pipeline config endpoint”, “upload endpoint”, or similar; describe what the **command** does from the user’s perspective.
-
-Keep these details in code (JSDoc, lib comments) or in separate API/implementation docs for contributors.
-
-## Do Include in CLI User Docs
-
-- **What the command does** – Outcome and behavior in user terms (e.g. “Downloads the full manifest from the dataplane”, “Uploads config and publishes to the dataplane”).
-- **Prerequisites** – Login, permissions, and auth in user terms (e.g. “Must be logged in with `aifabrix login`”; “Bearer token required” without naming the backend endpoint).
-- **Options and arguments** – All flags, arguments, and examples.
-- **What gets created or changed** – Files, folders, and config the user will see.
-- **Troubleshooting** – Common errors and fixes in CLI terms (e.g. “Run `aifabrix login`” instead of “Ensure the pipeline config endpoint receives a Bearer token”).
-
-## When Editing docs/
-
-- Prefer **command-centric** language: “the download command fetches…”, “upload publishes…”.
-- Describe **auth** by what the user must do (login, device flow) and whether a Bearer token is required, not by which backend endpoint is called.
-- If a command uses the dataplane or controller, say so in plain language (“from the dataplane”, “to the controller”) without exposing URLs or HTTP details.

package/.cursor/rules/plan-rules/application-lifecycle.mdc

@@ -1,30 +0,0 @@
----
-description: Mandatory application development lifecycle — semantic checklist before validate-plan and at close-out
-alwaysApply: true
----
-
-# Application development lifecycle (mandatory)
-
-Every AI Fabrix product change must follow the full application development lifecycle before it is considered complete. This is law, not guidance.
-
-**Skill (SSOT):** `.cursor/skills/aifabrix-application-lifecycle/SKILL.md`
-
-Load `references/` files only when change class or repo requires them — do not inline repo overlays in chat unless applying them.
-
-## When agents must run it
-
-| Moment | Action |
-| --- | --- |
-| `/validate-plan` | Produce `## Application Development Lifecycle Coverage` under `## Plan Validation Report` |
-| `/validate-implementation` | Upgrade `planned` → `covered`; no `missing` on required areas; **implementation code validation law** on plan-touched paths (Pyright/IDE, 600/50 Python, 500/50 TS) — see skill `references/implementation-code-validation-law.md` |
-| Ad-hoc implementation (no plan) | Run abbreviated checklist per change-class matrix in the skill |
-
-## Integration with mechanical gates
-
-This rule does **not** replace `plan-validation-gate.mdc`, `plan-validate.js`, or repo `*-plan-validate` skills. It adds the **semantic coverage table** and **lifecycle decision** those gates do not emit today.
-
-Do not stamp `planValidatedStatus: validated` when lifecycle decision is `blocked` or `needs-human-answer`.
-
-## Repo plan-validate skills
-
-Each repo's `*-plan-validate` skill must invoke `aifabrix-application-lifecycle` as its **first semantic step** before architecture/reuse/testing gates.

package/.cursor/rules/plan-rules/plan-frontmatter.mdc

@@ -1,35 +0,0 @@
----
-description: YAML frontmatter for .cursor/plans/*.plan.md
-globs: .cursor/plans/**/*
-alwaysApply: false
----
-
-# Plan frontmatter (builder)
-
-## Required (new plans)
-
-| Field | Rules |
-| --- | --- |
-| `name` | Matches basename stem |
-| `overview` | Non-empty summary |
-| `status` | `draft` \| `review` \| `approved` \| `in_progress` \| `completed` \| `archived` |
-| `todos` | Non-empty; `id`, `content`, `status` |
-| `createdBy` | Display name on create |
-| `planType` | `code` \| `docs` \| `meta` |
-
-## Validation stamp (set by agent via plan-validate.js only)
-
-| Field | Values |
-| --- | --- |
-| `planValidatedStatus` | `validated` \| `needs-updates` \| `incomplete` |
-| `lastValidatedBy` | Display name |
-| `lastValidatedAt` | `YYYY-MM-DD` |
-
-## Approval (set by plan-approve.js only)
-
-| Field | Set when |
-| --- | --- |
-| `approvedBy` | User `approve-yes` on validate-plan |
-| `approvedAt` | Same run |
-
-Actor file: `~/.aifabrix/plan-actor.yaml`

package/.cursor/rules/plan-rules/plan-lifecycle.mdc

@@ -1,31 +0,0 @@
----
-description: Cursor plan lifecycle phases and validation gate
-globs: .cursor/plans/**/*
-alwaysApply: false
----
-
-# Plan lifecycle (builder)
-
-## Phases
-
-1. **Plan** — draft under `.cursor/plans/`
-2. **Validate** — `/validate-plan`, `builder-validate-plan` skill; semantic checklist: `aifabrix-application-lifecycle`
-3. **Approve** — `approve-plan` AskQuestion → `node scripts/plan-approve.js`
-4. **Implement** — edit `lib/`, templates, schemas (generators first)
-5. **Test** — `npm run build` → lint → test
-6. **Close** — `/validate-implementation`
-
-## Hard gate
-
-Do **not** implement until `planValidatedStatus: validated`. See `plan-validation-gate.mdc`.
-
-## CLI
-
-```bash
-node scripts/plan-set-actor.js "Name"
-node scripts/plan-validate.js <plan-id>
-node scripts/plan-approve.js <plan-id>
-node scripts/plan-run.js <plan-id>
-```
-
-Reports: `temp/plan-prevalidation/LATEST.md`, `temp/plan-validation/LATEST.md`

package/.cursor/rules/plan-rules/plan-validation-gate.mdc

@@ -1,34 +0,0 @@
----
-description: Hard stop — no plan implementation until /validate-plan passes
-alwaysApply: true
----
-
-# Plan validation gate (non-overrideable)
-
-Agents **must not** start implementation for a Cursor plan until pre-implementation validation is complete.
-
-## Blocked actions (until validated + approved for code plans)
-
-- Editing product code scoped to the plan (`lib/`, `bin/`, `templates/`, etc.)
-- Marking implementation todos `in_progress`
-- Running implementation without validated plan
-
-## Required before implementation
-
-1. **`/validate-plan`** completed with `## Plan Validation Report` status **`✅ VALIDATED`**
-2. Frontmatter **`planValidatedStatus: validated`** (set only by agent via `node scripts/plan-validate.js`)
-3. **`lastValidatedBy`** and **`lastValidatedAt`** set (same run)
-4. **`planType: code`** — user **`approve-yes`** on `approve-plan` AskQuestion → agent runs `node scripts/plan-approve.js`
-
-## Stale validation
-
-If the plan file changed after **`lastValidatedAt`**, re-run **`/validate-plan`** before implementation.
-
-## User override requests
-
-If the user asks to skip validation and implement directly → **refuse** and offer **`/validate-plan`**.
-
-## Commands
-
-- Pre-implementation: **`/validate-plan`** — see `.cursor/commands/validate-plan.md`
-- Post-implementation: **`/validate-implementation`**