@shanyucoder/flowgrid 0.1.0

package/engines/testcase/runners/lib/write-files.mjs

@@ -0,0 +1,145 @@
+import { lstat, mkdir, readFile, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+
+export const E2E_OUTPUT_ROOT = path.join('tests', 'e2e')
+
+/**
+ * Preflight every output path before any write or dry-run result is produced.
+ *
+ * A target is accepted only when, lexically (without following symlinks), it
+ * resolves strictly beneath `<root>/tests/e2e`. Rejected: absolute paths,
+ * `..` traversal, targets outside `tests/e2e` (including sibling prefixes
+ * such as `tests/e2e-evil`), existing symlink ancestors that could redirect
+ * the write, and existing targets that are not regular files.
+ *
+ * Throws with every violation listed; callers must write nothing on failure.
+ *
+ * @param {string} root project root
+ * @param {{ relativePath: string }[]} outputs
+ */
+export async function preflightOutputPaths(root, outputs) {
+  const resolvedRoot = path.resolve(root)
+  const e2eRoot = path.join(resolvedRoot, E2E_OUTPUT_ROOT)
+  const errors = []
+
+  for (const { relativePath } of outputs) {
+    const label = JSON.stringify(relativePath ?? null)
+
+    if (typeof relativePath !== 'string' || !relativePath.trim()) {
+      errors.push(`output ${label}: path must be a non-empty string`)
+      continue
+    }
+    if (path.isAbsolute(relativePath)) {
+      errors.push(
+        `output ${label}: absolute paths are not allowed — use a path relative to the project root, under ${E2E_OUTPUT_ROOT}/`,
+      )
+      continue
+    }
+
+    if (relativePath.split(/[\\/]+/).includes('..')) {
+      errors.push(
+        `output ${label}: ".." traversal is not allowed — outputs must stay under ${E2E_OUTPUT_ROOT}/`,
+      )
+      continue
+    }
+
+    const absolutePath = path.resolve(resolvedRoot, relativePath)
+    if (!absolutePath.startsWith(e2eRoot + path.sep)) {
+      errors.push(
+        `output ${label}: resolves outside ${E2E_OUTPUT_ROOT}/ — generated files must live beneath <projectRoot>/${E2E_OUTPUT_ROOT}` +
+          ' (check module/testcase ids used to build output paths)',
+      )
+      continue
+    }
+
+    const symlinkIssue = await findUnsafePathComponent(resolvedRoot, absolutePath)
+    if (symlinkIssue) errors.push(`output ${label}: ${symlinkIssue}`)
+  }
+
+  if (errors.length) {
+    throw new Error(
+      `testcase-gen: refusing to write — ${errors.length} unsafe output path(s), nothing was written:\n` +
+        errors.map((message) => `  - ${message}`).join('\n'),
+    )
+  }
+}
+
+/**
+ * Walk each existing path component from root down to the target without
+ * following symlinks. Any symlink component (or non-regular existing target)
+ * could escape or redirect the write and is rejected. Missing components are
+ * fine: they are created later as real directories.
+ *
+ * @param {string} resolvedRoot
+ * @param {string} absolutePath
+ * @returns {Promise<string | null>} violation message, or null when safe
+ */
+async function findUnsafePathComponent(resolvedRoot, absolutePath) {
+  const segments = path.relative(resolvedRoot, absolutePath).split(path.sep)
+  let current = resolvedRoot
+
+  for (let i = 0; i < segments.length; i++) {
+    current = path.join(current, segments[i])
+    let stats
+    try {
+      stats = await lstat(current)
+    } catch {
+      return null
+    }
+    const componentRel = path.relative(resolvedRoot, current)
+    const isTarget = i === segments.length - 1
+    if (stats.isSymbolicLink()) {
+      return `existing ${isTarget ? 'target' : 'ancestor'} "${componentRel}" is a symlink — remove it so writes cannot be redirected outside ${E2E_OUTPUT_ROOT}/`
+    }
+    if (isTarget && !stats.isFile()) {
+      return `existing target "${componentRel}" is not a regular file`
+    }
+    if (!isTarget && !stats.isDirectory()) {
+      return `existing ancestor "${componentRel}" is not a directory`
+    }
+  }
+
+  return null
+}
+
+/**
+ * @param {string} root
+ * @param {{ relativePath: string, content: string }[]} outputs
+ * @param {{ dryRun?: boolean, force?: boolean }} options
+ */
+export async function writeOutputs(root, outputs, options = {}) {
+  await preflightOutputPaths(root, outputs)
+
+  const written = []
+  const skipped = []
+
+  for (const { relativePath, content } of outputs) {
+    const absolutePath = path.join(root, relativePath)
+    const exists = await fileExists(absolutePath)
+
+    if (exists && !options.force) {
+      skipped.push({ relativePath, reason: 'exists (use --force)' })
+      continue
+    }
+
+    if (options.dryRun) {
+      written.push({ relativePath, dryRun: true })
+      continue
+    }
+
+    await mkdir(path.dirname(absolutePath), { recursive: true })
+    await writeFile(absolutePath, content, 'utf8')
+    written.push({ relativePath })
+  }
+
+  return { written, skipped }
+}
+
+async function fileExists(filePath) {
+  try {
+    await readFile(filePath)
+    return true
+  } catch {
+    return false
+  }
+}

package/engines/testcase/runners/validate-registry.mjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+import path from 'node:path'
+import { access } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+
+import { loadE2eTestRegistry, REGISTRY_REL, resolveBundleMatchers } from './lib/e2e-registry.mjs'
+
+const root = path.resolve(process.env.FLOWGRID_PROJECT_ROOT || process.env.FLOWGRID_PROJECT_ROOT || process.cwd())
+
+async function pathExists(relativePath) {
+  try {
+    await access(path.join(root, relativePath))
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function main() {
+  const { registry } = await loadE2eTestRegistry(root)
+  const errors = []
+  const warnings = []
+  const bundles = registry.bundles ?? {}
+  const matchers = registry.matchers ?? {}
+
+  console.log(`e2e-test.registry v${registry.version}`)
+  console.log(`  path: ${REGISTRY_REL}`)
+  console.log(`  bundles: ${Object.keys(bundles).join(', ')}`)
+
+  if (registry.fixture) {
+    const exists = await pathExists(registry.fixture)
+    if (!exists) errors.push(`fixture: missing ${registry.fixture}`)
+  }
+
+  for (const [id, bundle] of Object.entries(bundles)) {
+    if (bundle.status === 'planned') {
+      warnings.push(`bundle ${id}: planned`)
+      continue
+    }
+    for (const matcher of resolveBundleMatchers(id, bundles)) {
+      if (!matchers[matcher]) {
+        errors.push(`bundle ${id}: unknown matcher "${matcher}"`)
+      }
+    }
+    for (const parent of bundle.extends ?? []) {
+      if (!bundles[parent]) {
+        errors.push(`bundle ${id}: extends unknown bundle "${parent}"`)
+      }
+    }
+  }
+
+  for (const [id, meta] of Object.entries(matchers)) {
+    if (!meta.layer) {
+      warnings.push(`matcher ${id}: missing layer`)
+    }
+  }
+
+  for (const warning of warnings) {
+    console.warn(`  warn: ${warning}`)
+  }
+
+  if (errors.length) {
+    for (const error of errors) {
+      console.error(`  error: ${error}`)
+    }
+    process.exit(1)
+  }
+
+  console.log('flowgrid:e2e-registry OK')
+}
+
+main().catch((error) => {
+  console.error(error.message ?? error)
+  process.exit(1)
+})

package/engines/testcase/templates/api.spec.ts.hbs

@@ -0,0 +1,40 @@
+// Generated by testcase:gen:api — edit via TC YAML (genType: api-e2e) + re-gen with --force
+
+import { test, expect } from '@playwright/test'
+
+const BASE_URL = process.env.{{baseUrlEnv}} ?? '{{defaultBaseUrl}}'
+
+{{#if hasDefaultHeaders}}
+const DEFAULT_HEADERS = {{{json defaultHeaders}}} as Record<string, string>
+{{/if}}
+
+test.describe('{{testcaseId}} — {{testcaseTitle}}', () => {
+{{#each apiSteps}}
+  test('{{label}}', async ({ request }) => {
+    const url = `${BASE_URL}{{path}}`
+    const headers = {
+      {{#if ../hasDefaultHeaders}}...DEFAULT_HEADERS,{{/if}}
+      {{#if headers}}...{{{json headers}}},{{/if}}
+    }
+    const options = {
+      headers,
+      {{#if hasBody}}
+      data: {{{json body}}},
+      {{/if}}
+    }
+    const response = await request.{{methodFn}}(url, options)
+    expect(response.status()).toBe({{expectStatus}})
+    {{#if hasExpectBodyContains}}
+    const text = await response.text()
+    expect(text).toContain('{{expectBodyContains}}')
+    {{/if}}
+    {{#if hasExpectJson}}
+    const json = await response.json()
+    {{#each expectJsonEntries}}
+    expect(json['{{key}}']).toEqual({{{valueJson}}})
+    {{/each}}
+    {{/if}}
+  })
+
+{{/each}}
+})

package/engines/testcase/templates/page.ts.hbs

@@ -0,0 +1,69 @@
+// Generated by testcase:gen — edit via testcase YAML + re-gen with --force
+import type { Page } from '@playwright/test'
+import { expect } from '@playwright/test'
+
+import { waitForSemanticUiReady } from '../../helpers/semantic-ui/renderReady'
+
+export class {{pageClassName}} {
+  constructor(private readonly page: Page) {}
+
+  async goto(path = '{{routePath}}') {
+    await this.page.goto(path)
+  }
+
+  async waitForTestId(testId: string) {
+    await expect(this.page.getByTestId(testId)).toBeVisible()
+  }
+
+  async waitForRole(role: string, name?: RegExp | string) {
+    const locator = name !== undefined
+      ? this.page.getByRole(role as Parameters<Page['getByRole']>[0], { name })
+      : this.page.getByRole(role as Parameters<Page['getByRole']>[0])
+    await locator.waitFor()
+  }
+
+  async fill(testId: string, value: string) {
+    await this.page.getByTestId(testId).fill(value)
+  }
+
+  async click(testId: string) {
+    await this.page.getByTestId(testId).click()
+  }
+
+  async expectTestIdVisible(testId: string, visible: boolean) {
+    const locator = this.page.getByTestId(testId)
+    if (visible) {
+      await expect(locator).toBeVisible()
+    } else {
+      await expect(locator).not.toBeAttached()
+    }
+  }
+
+{{#if specActions.length}}
+  // Action triggers
+{{#each specActions}}
+  async trigger{{pascalCase id}}() {
+    // TODO: implement trigger for {{id}} (trigger type: {{trigger}})
+  }
+{{/each}}
+{{/if}}
+
+{{#if hasI18n}}
+  // I18N Helper
+  async expectTextVisible(text: string) {
+    await expect(this.page.getByText(text, { exact: true })).toBeVisible()
+  }
+{{/if}}
+
+
+{{#if semanticReady}}
+  async waitForSemanticReady() {
+    await waitForSemanticUiReady(this.page, {
+      rootTestId: '{{semanticReady.rootTestId}}'{{#if semanticReady.waitForTestIds}},
+      waitForTestIds: [{{#each semanticReady.waitForTestIds}}'{{this}}'{{#unless @last}}, {{/unless}}{{/each}}]{{/if}}{{#if semanticReady.waitForFonts}},
+      waitForFonts: true{{/if}}{{#if semanticReady.waitForImages}},
+      waitForImages: '{{semanticReady.waitForImages}}'{{/if}}
+    })
+  }
+{{/if}}
+}

package/engines/testcase/templates/partials/README.md

@@ -0,0 +1,5 @@
+# testcase-gen partials
+
+Semantic + axe assertion **code** is generated in `lib/semantic-plan.mjs` from `registries/e2e-test.registry.json`.
+
+Handlebars partials for functional steps remain in `spec.ts.hbs`. Future flow partials (delete, confirm dialog) will land here as `partials/flow-*.hbs`.

package/engines/testcase/templates/spec.ts.hbs

@@ -0,0 +1,231 @@
+// Generated by testcase:gen — edit via testcase YAML + re-gen with --force
+
+{{#if useSemanticFixture}}
+
+import { expect, test } from '../fixtures/semantic-ui'
+
+{{else}}
+
+import { test } from '@playwright/test'
+
+{{/if}}
+
+
+
+import { applyTestcaseMocks, applyTestcaseSession } from '../helpers/applyTestcaseMocks'
+
+import { assertRequestMatches, expectNewTabWithUrl, whenNetworkRequest } from '../helpers/testcaseAssertions'
+
+{{#if hasLegacyLayoutOnly}}
+
+import { assertLayoutIntegrity } from '../helpers/assertLayoutIntegrity'
+
+{{/if}}
+
+import { resolvePlaceholder, resolveTestcaseData, resolveTestIdTemplate } from '../helpers/testcaseData'
+
+import { {{pageClassName}} } from '../pages/{{module}}/{{pageClassName}}'
+
+
+
+const TESTCASE_MOCKS = {{json mocks}}
+
+{{#if hasData}}
+
+const TESTCASE_DATA = resolveTestcaseData({{{json data}}})
+
+{{/if}}
+
+{{#if hasI18n}}
+
+// I18N Dictionary from component spec
+const I18N_DICT = {{{json specI18n}}}
+
+{{/if}}
+
+
+
+test.describe('{{testcaseId}}', () => {
+
+  test.beforeEach(async ({ page }) => {
+
+{{#if session}}
+
+    await applyTestcaseSession(page, '{{session}}')
+
+{{/if}}
+
+    await applyTestcaseMocks(page, TESTCASE_MOCKS)
+
+{{#if specActions.length}}
+    // Actions from component spec (available for mocking):
+{{#each specActions}}
+    // - Action: {{id}} (trigger: {{trigger}})
+{{#each onSpecificError}}
+    //   Handle {{condition}}: await page.route('**/*', route => route.fulfill({ status: parseInt('{{condition}}', 10) || 500 }))
+{{/each}}
+{{/each}}
+{{/if}}
+
+  })
+
+
+
+  test('{{testcaseTitle}}', async ({ page{{#if needsConsoleErrors}}, consoleErrors{{/if}} }) => {
+
+    const po = new {{pageClassName}}(page)
+
+{{#if hasData}}
+
+    const data = TESTCASE_DATA
+
+{{/if}}
+
+
+
+{{#each setupSteps}}
+
+{{#if (eq action 'goto')}}
+
+    await po.goto('{{path}}')
+
+{{/if}}
+
+{{#if (eq action 'waitFor')}}
+
+{{#if testId}}
+
+    await po.waitForTestId('{{testId}}')
+
+{{else if role}}
+
+    await po.waitForRole('{{role}}'{{#if roleNameExpr}}, {{roleNameExpr}}{{/if}})
+
+{{/if}}
+
+{{/if}}
+
+{{#if (eq action 'fill')}}
+
+    await po.fill('{{testId}}', {{#if (startsWith value '{{')}}resolvePlaceholder('{{value}}', data){{else}}'{{value}}'{{/if}})
+
+{{/if}}
+
+{{/each}}
+
+{{#each uiVisibility}}
+
+    await po.expectTestIdVisible('{{testId}}', {{visible}})
+
+{{/each}}
+
+{{#if (and networkAssertions.length (not hasNewTabAction))}}
+
+{{#each networkAssertions}}
+
+    const networkResponse{{@index}} = whenNetworkRequest(page, {
+
+      method: '{{method}}',
+
+      path: '{{path}}',
+
+      bodyContains: {{{json bodyContains}}}
+
+    })
+
+{{/each}}
+
+{{#each clickSteps}}
+
+{{#if (includes testId '{{')}}
+
+    await po.click(resolveTestIdTemplate('{{testId}}', data))
+
+{{else}}
+
+    await po.click('{{testId}}')
+
+{{/if}}
+
+{{/each}}
+
+{{#each networkAssertions}}
+
+    await assertRequestMatches(await networkResponse{{@index}}, {
+
+      method: '{{method}}',
+
+      path: '{{path}}',
+
+      bodyContains: {{{json bodyContains}}}
+
+    }, {{#if ../hasData}}data{{else}}{}{{/if}})
+
+{{/each}}
+
+{{/if}}
+
+{{#each uiActions}}
+
+{{#if (eq action 'newTabOpened')}}
+
+{{#if ../primaryNetwork}}
+
+    const networkResponseTab = whenNetworkRequest(page, {
+
+      method: '{{../primaryNetwork.method}}',
+
+      path: '{{../primaryNetwork.path}}',
+
+      bodyContains: {{{json ../primaryNetwork.bodyContains}}}
+
+    })
+
+{{/if}}
+
+    await expectNewTabWithUrl(page, async () => {
+
+      await po.click(resolveTestIdTemplate('{{clickTemplate}}', data))
+
+    }, '{{urlContains}}')
+
+{{#if ../primaryNetwork}}
+
+    await assertRequestMatches(await networkResponseTab, {
+
+      method: '{{../primaryNetwork.method}}',
+
+      path: '{{../primaryNetwork.path}}',
+
+      bodyContains: {{{json ../primaryNetwork.bodyContains}}}
+
+    }, data)
+
+{{/if}}
+
+{{/if}}
+
+{{/each}}
+
+{{#if semanticReady}}
+
+    await po.waitForSemanticReady()
+
+{{/if}}
+
+{{#each semanticCodegenLines}}
+
+    {{{this}}}
+
+{{/each}}
+
+{{#if hasLegacyLayoutOnly}}
+
+    await assertLayoutIntegrity(page, { skipOverlap: true })
+
+{{/if}}
+
+  })
+
+})
+

package/harness/agents/claude/rules/claude-flowgrid.mdc

@@ -0,0 +1,9 @@
+---
+description: Claude Code — FlowGrid MCP wiring
+alwaysApply: false
+---
+# Claude Code + FlowGrid
+
+- MCP: `.claude/mcp.json`, server `flowgrid`.
+- Skills: `.claude/skills/<name>/SKILL.md`.
+- Re-sync: `flowgrid harness sync --agent=claude`.

package/harness/agents/cursor/rules/cursor-flowgrid.mdc

@@ -0,0 +1,9 @@
+---
+description: Cursor — FlowGrid MCP wiring
+alwaysApply: false
+---
+# Cursor + FlowGrid
+
+- MCP: `.cursor/mcp.json`, server `flowgrid`.
+- Skills: `.cursor/skills/<name>/SKILL.md`.
+- Re-sync: `flowgrid harness sync --agent=cursor`.

package/harness/agents/gemini_antigravity/rules/antigravity-mcp.mdc

@@ -0,0 +1,10 @@
+---
+description: Antigravity — FlowGrid MCP wiring (mcp_config.json)
+alwaysApply: false
+---
+# Antigravity + FlowGrid
+
+- MCP config file: `.agents/mcp_config.json` (not `mcp.json`).
+- Server name: `flowgrid` → `bin/flowgrid-mcp.mjs` from the FlowGrid package used at `flowgrid init`.
+- Skills live under `.agents/skills/`; rules under `.agents/rules/`.
+- Re-sync after config changes: `flowgrid harness sync --agent=gemini_antigravity`.

package/harness/agents/kiro/rules/kiro-flowgrid.mdc

@@ -0,0 +1,9 @@
+---
+description: Kiro — FlowGrid MCP wiring
+alwaysApply: false
+---
+# Kiro + FlowGrid
+
+- MCP: `.kiro/mcp.json`, server `flowgrid`.
+- Skills: `.kiro/skills/<name>/SKILL.md`.
+- Re-sync: `flowgrid harness sync --agent=kiro`.

package/harness/be/adapters/dotnet-integration/skills/framework-rules-be/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: framework-rules-be
+description: .NET Integration BE conventions — gen-first, clear boundaries
+disable-model-invocation: true
+---
+
+# Platform Base (.NET Integration BE)
+
+**Owner:** Platform DNA (`--type=be|monolith --be-adapter=dotnet-integration`)
+
+.NET integration host · bộ code grill/gen first when applicable.
+
+## Gen trước (code)
+
+1. Prefer codegen / existing templates before free-form scaffolding
+2. AI fills gaps only — do not duplicate generated surfaces
+
+## Checklist
+
+- [ ] Clear API / application / infrastructure boundaries
+- [ ] Contracts align with docs hub when present

package/harness/be/adapters/fastapi/skills/framework-rules-be/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: framework-rules-be
+description: FastAPI BE conventions — modules, gen-first, thin routers; see stack docs
+disable-model-invocation: true
+---
+
+# Platform Base (FastAPI BE)
+
+**Owner:** Platform DNA (`--type=be|monolith --be-adapter=fastapi`)
+
+FastAPI · modular packages · bộ code grill/gen first.
+
+## Gen trước (code)
+
+1. bộ code `gen` / repo shim from IR already grilled
+2. AI only fills `#needs-*` / gaps not yet in `registries/`
+3. Do not hand-write boilerplate codegen already covers
+
+## Layers
+
+`router` → `service` / `use-case` → `repository` / adapters → models/schemas  
+Keep routers thin. Domain rules stay out of transport.
+
+## Checklist
+
+- [ ] Module boundaries clear · no god routers
+- [ ] Contracts align with docs hub OpenAPI / IR when present

package/harness/be/adapters/laravel/skills/framework-rules-be/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: framework-rules-be
+description: Laravel BE conventions — modules-v1, gen-first, thin controllers
+disable-model-invocation: true
+---
+
+# Platform Base (Laravel BE)
+
+**Owner:** Platform DNA (`--type=be|monolith --be-adapter=laravel`)
+
+Laravel · `nwidart/laravel-modules` (modules-v1) · bộ code grill/gen first.
+
+## Gen trước (code)
+
+1. bộ code `gen` / repo shim from IR already grilled
+2. AI only fills `#needs-*` / gaps not yet in registries
+3. Do not hand-write module scaffolding codegen already covers
+
+## Layers
+
+`Http` (controllers/requests) → Actions/Services → Models/Repositories  
+Controllers stay thin. Prefer module-local code under `Modules/`.
+
+## Checklist
+
+- [ ] modules-v1 layout · no cross-module leaks
+- [ ] Contracts align with docs hub when present