@shanyucoder/flowgrid 0.1.0

package/lexicon/registry-tags.en.txt

@@ -0,0 +1,173 @@
+# ArtifactGraph generic registry-tag vocabulary.
+# Lexicon only; product registries/*.json remain SSOT.
+
+================================================================================
+PREFIXES
+================================================================================
+#shell:       page / screen templates
+#widget:      field and composite controls
+#pattern:     product or page flows
+#behavior:    interaction and feedback
+#style:       visual density / theme
+#region:      layout regions
+#api:         HTTP/resource contract
+#logic:       business rules, jobs, events
+#data:        field empty/PII policies
+#auth:        authentication
+#authz:       authorization
+#tenancy:     tenant boundary
+#process:     capability / process / E2E / use case / scenario
+#common:      promoted shared artifact
+#needs-*      missing artifact
+#missing_info business fact gap (FlowGrid bộ docs) — leave empty / grill; do not invent
+
+================================================================================
+A. UI — shells / page types
+================================================================================
+List / Index / Directory
+Detail / Show / Read-only view
+Create / New / Form
+Edit / Update
+Dashboard / Overview
+Wizard / Stepper / Multi-step
+Settings / Preferences
+Workspace / Canvas
+DataListPage · DataDetailPage · DataFormPage · DashboardPage · WizardPage · SettingsPage · WorkspacePage
+
+================================================================================
+B. UI — layout / controls
+================================================================================
+Header / Sidebar / Breadcrumb / Toolbar / Filters / Content / Footer
+Drawer / v-navigation-drawer / mat-drawer / Modal / Dialog / v-dialog / mat-dialog / Popover / v-menu / Toast / Snackbar / v-snackbar / mat-snackbar / Banner / Tabs / v-tabs / mat-tab / Accordion / v-expansion-panels / mat-expansion-panel
+Text field / v-text-field / mat-input / Textarea / v-textarea / Number / Currency / Date / Select / v-select / mat-select / Combobox / v-combobox
+Checkbox / v-checkbox / mat-checkbox / Radio / v-radio / mat-radio / Switch / v-switch / mat-slide-toggle / File upload / v-file-input / Password / Search field
+Data table / v-data-table / mat-table / Grid / Kanban / Calendar / Chart / KPI card
+Status chip / Badge / Pill / v-chip / mat-chip / v-badge / mat-badge
+Button / v-btn / mat-button / IconButton / mat-icon-button
+Pagination / Sort control / Bulk actions / Row actions
+
+================================================================================
+C. UI — behavior
+================================================================================
+Loading / Skeleton / Spinner
+Optimistic update
+Debounce / Throttle search
+Confirm destructive
+Soft delete / Archive
+Autosave / Dirty guard
+Inline edit
+Responsive / Compact / Dense
+Accessibility / Focus trap
+Permission-aware / RBAC-gated
+
+================================================================================
+F. Product patterns
+================================================================================
+CRUD
+Delete flow / Delete
+Confirm dialog / Confirmation
+Search / Select / Act
+Import / Export / Bulk upload
+Approval / Workflow / Review queue
+Audit log / Activity feed
+Assignment / Ownership
+Feature flag / Beta
+Multi-tenant / Org switcher
+Preview / Draft / Publish
+
+================================================================================
+G. API — resource & contract
+================================================================================
+Resource / Collection / Item
+Endpoint / Operation / Action
+Idempotent / Upsert / Batch / Bulk
+Partial update / PATCH
+Soft delete / Restore
+Pagination / Filter / Sort / Search
+Rate limit / Versioned API / Webhook
+Long-running / Job / Async / Realtime
+#api: op:list|create|update|delete|show
+#api: pagination:cursor
+#api: async-job
+
+================================================================================
+H. API — AuthN / AuthZ / tenancy
+================================================================================
+Authentication / Authorization
+Session / JWT / Refresh token
+OAuth / SSO / API key / Service account
+Scope / Permission / Role / Policy
+Tenant / Workspace / Org
+Row-level security
+
+================================================================================
+I. Logic — domain & consistency
+================================================================================
+Business rule / Invariant
+Validation / Uniqueness / Conflict
+State machine / Status transition
+Transaction / Unit of work
+Event / Domain event
+Saga / Compensation / Outbox
+Retry / Backoff / Dead letter / Circuit breaker
+
+================================================================================
+J. Data field policies
+================================================================================
+Nullable / Optional / Required
+Empty string vs null vs omit
+Default value / Computed / Derived
+Immutable after create
+PII / Sensitive / Masked
+#data: empty:null|empty-string|omit|empty-array
+#data: pii
+#data: immutable
+
+================================================================================
+K. Business architecture — process hierarchy & synonyms
+================================================================================
+Business Capability
+Business Process
+End-to-End Flow / E2E Flow
+Use Case
+Scenario
+Functional Requirement
+Business Flow / Workflow / BPMN Process
+Journey / Customer Journey
+Cross-Service Flow / Service Orchestration / Service Choreography
+Saga Flow / Distributed Transaction
+Domain Workflow / Event Flow / Command Flow
+#process: business-capability
+#process: business-process
+#process: e2e-flow
+#process: use-case
+#process: scenario
+#process: workflow
+#process: journey
+#process: cross-service-flow
+#process: orchestration
+#process: choreography
+#process: saga
+#process: domain-flow
+#process: event-flow
+#process: command-flow
+
+================================================================================
+L. API Reuse / Integration markers
+================================================================================
+Hashtags enforced by ArtifactGraph duplicate-route detection and FlowGrid bộ docs grill rules.
+
+#reuse-api        Reused endpoint from common/sibling module — skip duplicate spec gen
+#call-external    Third-party integration call (OAuth, SMS, Payment, Webhook, MES/ERP)
+#cross-service    Multi-aggregate synchronous internal orchestration (single bounded context)
+#cross-entity-service  Multi-entity cross-aggregate orchestration (alias cross-service)
+#derived-data     Internal computed/derived backend data field (not stored, not on entity)
+#needs-component  UI component missing in design registry or requiring template .hbs
+#missing_info     Business field/flow/validation unknown — FlowGrid bộ docs grill hard gate; do not invent
+
+#reuse-api
+#call-external
+#cross-service
+#cross-entity-service
+#derived-data
+#missing_info

package/lexicon/testcase-taxonomy.en.txt

@@ -0,0 +1,117 @@
+# ArtifactGraph generic test-case taxonomy.
+# Lexicon only; product test cases and suites remain SSOT.
+
+================================================================================
+LEVEL 1 — TEST SCENARIO
+================================================================================
+Authentication
+Authorization
+Validation
+Security
+Session
+Performance
+Compatibility
+Accessibility
+Error Handling
+Localization
+Usability
+Data Integrity
+Workflow
+Permissions
+Notifications
+Import / Export
+Search / Filter
+Audit / Logging
+
+================================================================================
+LEVEL 2 — TEST CATEGORIES
+================================================================================
+Required field
+Format validation
+Length validation
+Boundary validation
+Business validation
+Valid credential
+Invalid credential
+Role allow
+Role deny
+Happy path transition
+Illegal transition
+Concurrent edit
+Mock / Stub / Spy / Fixture
+AAA pattern (Arrange, Act, Assert)
+Snapshot match
+
+================================================================================
+LEVEL 3 — TEST CASE NAMING
+================================================================================
+Prefer action + condition + expected result.
+
+================================================================================
+MODERN CASE TYPES
+================================================================================
+happy-path           Successful path / intended outcome
+validation           Input / form / business validation rejection
+boundary             Min/max and neighboring values
+authorization        Role allow/deny and privilege checks
+state-transition     Legal and illegal status changes
+exception            Errors, timeouts, and surfaced failures
+concurrency          Multi-user / multi-tab behavior
+audit                Audit and logging outcomes
+accessibility        Keyboard, screen reader, color contrast, focus management, aria-labels, axe-core
+localization         Timezone, currency, language, date format
+data-integrity       Visible consistency after operations
+integration          Cross-module / Integration flow
+e2e                  End-to-End / Browser test / Playwright / Cypress
+
+================================================================================
+THREE FILTER DIMENSIONS
+================================================================================
+business:
+crud
+workflow
+permission
+business-rule
+
+technical:
+validation
+ui
+api
+database
+messaging
+realtime
+file-storage
+offline
+retry
+
+quality:
+security
+performance
+reliability
+recovery
+audit
+logging
+monitoring
+accessibility
+localization
+compatibility
+
+================================================================================
+CASE YAML FIELD VOCABULARY
+================================================================================
+id
+title
+summary
+refs
+coverage
+priority
+preconditions
+testData
+steps
+expected
+postcondition
+automation
+tags
+dimensions.business
+dimensions.technical
+dimensions.quality

package/package.json

@@ -0,0 +1,98 @@
+{
+  "name": "@shanyucoder/flowgrid",
+  "version": "0.1.0",
+  "description": "Unified Local MCP Toolkit (Graph, DNA, Docs, Test, Codegen)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "flowgrid": "./bin/flowgrid.mjs",
+    "flowgrid-mcp": "./bin/flowgrid-mcp.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ShanYuCoder/flowgrid.git"
+  },
+  "homepage": "https://github.com/ShanYuCoder/flowgrid#readme",
+  "bugs": {
+    "url": "https://github.com/ShanYuCoder/flowgrid/issues"
+  },
+  "keywords": [
+    "flowgrid",
+    "mcp",
+    "cli",
+    "codegen",
+    "spec",
+    "vitepress",
+    "ai-agent"
+  ],
+  "files": [
+    "bin",
+    "dist",
+    "scripts/prepare-install.mjs",
+    "adapters",
+    "engines",
+    "harness",
+    "templates",
+    "schemas",
+    "stacks",
+    "lexicon",
+    "README.md"
+  ],
+  "scripts": {
+    "dev": "pnpm docs:dev",
+    "build": "tsc",
+    "prepare": "node scripts/prepare-install.mjs",
+    "prepack": "npm run build",
+    "test": "pnpm run build && node --test test/*.test.mjs",
+    "check:pack": "npm pack --dry-run",
+    "publish:npm": "pnpm run check:pack && npm publish --access public",
+    "mcp": "node bin/flowgrid-mcp.mjs",
+    "cli": "node bin/flowgrid.mjs",
+    "audit:spec": "node engines/spec/lib/audit-bundle-gaps.mjs",
+    "audit:flow": "node engines/spec/lib/audit-flow-gaps.mjs",
+    "audit:api": "node engines/spec/lib/audit-api-gaps.mjs",
+    "audit:testcase": "node engines/spec/lib/audit-testcase-gaps.mjs",
+    "audit:legacy": "node engines/spec/lib/audit-legacy-gaps.mjs",
+    "audit:e2e": "node engines/spec/lib/audit-e2e-coverage.mjs",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.9.0",
+    "picocolors": "^1.1.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "yaml": "^2.9.0",
+    "zod": "^4.4.3",
+    "handlebars": "^4.7.8",
+    "ajv": "^8.20.0",
+    "cytoscape": "^3.34.0",
+    "cytoscape-cose-bilkent": "^4.1.0",
+    "ejs": "^3.1.10",
+    "mermaid": "^11.16.0",
+    "vitepress": "latest",
+    "vitepress-mermaid-renderer": "^1.1.28",
+    "vitepress-plugin-mermaid": "^2.0.17",
+    "vue": "^3.4.21",
+    "@braintree/sanitize-url": "^7.1.2",
+    "dayjs": "^1.11.21",
+    "debug": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.1",
+    "typescript": "^5.9.0",
+    "tsx": "^4.23.1"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
+  }
+}

package/schemas/missing-optional-event.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://platform.local/schemas/flowgrid-test/missing-optional-event.schema.json",
+  "title": "FlowGrid bộ test missing optional accelerator event",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "event",
+    "package",
+    "runId",
+    "optional",
+    "reason",
+    "fallback",
+    "metrics"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "1.0.0" },
+    "event": { "const": "flowgrid.missing-optional" },
+    "package": { "const": "@platform/flowgrid-test" },
+    "runId": { "type": "string", "minLength": 1 },
+    "optional": { "type": "string", "minLength": 1 },
+    "reason": {
+      "enum": ["not-configured", "unavailable", "invocation-failed"]
+    },
+    "fallback": { "type": "string", "minLength": 1 },
+    "metrics": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["fileReads", "contextBytes"],
+      "properties": {
+        "fileReads": { "type": "integer", "minimum": 0 },
+        "contextBytes": { "type": "integer", "minimum": 0 }
+      }
+    }
+  }
+}

package/schemas/testcase.schema.json

@@ -0,0 +1,239 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://platform.local/schemas/flowgrid-test/testcase.schema.json",
+  "title": "FlowGrid bộ test testcase YAML",
+  "type": "object",
+  "required": ["id", "title", "coverage", "refs", "genType", "feature"],
+  "additionalProperties": true,
+  "properties": {
+    "schemaVersion": {
+      "type": "integer",
+      "enum": [1, 2],
+      "description": "Use 2 for release gate (testMatrix + steps required)."
+    },
+    "id": { "type": "string", "pattern": "^TC-[A-Z0-9-]+$" },
+    "title": { "type": "string", "minLength": 1 },
+    "summary": { "type": "string" },
+    "story": { "type": "string" },
+    "coverage": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "enum": [
+          "happy",
+          "validation",
+          "boundary",
+          "authorization",
+          "state",
+          "exception",
+          "concurrency",
+          "audit",
+          "accessibility"
+        ]
+      }
+    },
+    "type": {
+      "description": "Removed on base — use coverage",
+      "not": {}
+    },
+    "refs": {
+      "type": "object",
+      "required": ["screen", "scenario"],
+      "anyOf": [
+        { "required": ["module"] },
+        { "required": ["component"] },
+        { "required": ["feature"] }
+      ],
+      "properties": {
+        "surface": { "type": "string" },
+        "module": { "type": "string", "pattern": "^(CMP|DEP|FLOW)-.*$" },
+        "capability": { "type": "string" },
+        "component": { "type": "string" },
+        "feature": { "type": "string" },
+        "rule": { "type": "string" },
+        "scenario": { "type": "string", "pattern": "^SC-.*$" },
+        "example": { "type": "string" },
+        "screen": { "type": "string", "pattern": "^(W|API|UI)-.*$" },
+        "target": {
+          "type": "string",
+          "not": { "pattern": "^CTR-" }
+        },
+        "api": { "type": "string" }
+      }
+    },
+    "genType": { "enum": ["e2e", "api-e2e"] },
+    "api": {
+      "type": "object",
+      "description": "Partner / webhook HTTP target (genType api-e2e).",
+      "properties": {
+        "baseUrlEnv": {
+          "type": "string",
+          "description": "process.env key for base URL (e.g. FLOWGRID_PARTNER_API_BASE)."
+        },
+        "baseURL": {
+          "type": "string",
+          "description": "Fallback base URL when env unset."
+        },
+        "defaultHeaders": {
+          "type": "object",
+          "additionalProperties": { "type": "string" }
+        }
+      }
+    },
+    "apiSteps": {
+      "type": "array",
+      "description": "Machine steps for testcase:gen:api (Playwright request).",
+      "items": {
+        "type": "object",
+        "required": ["method", "path"],
+        "properties": {
+          "id": { "type": "string" },
+          "method": {
+            "type": "string",
+            "enum": ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"]
+          },
+          "path": { "type": "string", "minLength": 1 },
+          "headers": { "type": "object", "additionalProperties": { "type": "string" } },
+          "body": {},
+          "expectStatus": { "type": "integer", "minimum": 100, "maximum": 599 },
+          "expectJson": { "type": "object" },
+          "expectBodyContains": { "type": "string" }
+        },
+        "additionalProperties": true
+      }
+    },
+    "feature": { "type": "string", "minLength": 1 },
+    "route": {
+      "type": "object",
+      "required": ["path"],
+      "properties": {
+        "path": { "type": "string" },
+        "auth": { "type": "string" }
+      }
+    },
+    "testIds": {
+      "type": "object",
+      "properties": {
+        "required": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "testMatrix": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["facet"],
+        "properties": {
+          "caseId": { "type": "string" },
+          "facet": {
+            "type": "string",
+            "enum": [
+              "positive_boundary",
+              "negative_length",
+              "negative_format",
+              "negative_duplicate",
+              "concurrency_double_submit",
+              "network_interruption"
+            ]
+          },
+          "description": { "type": "string", "minLength": 1 },
+          "input": { "type": "object" },
+          "action": { "type": "string" },
+          "expected": { "type": "object" }
+        },
+        "additionalProperties": true
+      }
+    },
+    "traceability": {
+      "type": "object",
+      "description": "Phase 3 bundle cross-refs (optional until gate strict).",
+      "properties": {
+        "bundleScreen": { "type": "string", "pattern": "^(W|API|UI)-.*$" },
+        "bundleScenarios": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "acceptanceRefs": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "actionRefs": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        }
+      },
+      "additionalProperties": false
+    },
+    "a11y": {
+      "type": "object",
+      "properties": {
+        "tags": { "type": "array", "items": { "type": "string" } },
+        "include": { "type": "array", "items": { "type": "string" } },
+        "exclude": { "type": "array", "items": { "type": "string" } },
+        "disableRules": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "priority": { "type": "string" },
+    "automation": { "type": "string" },
+    "tags": { "type": "array", "items": { "type": "string" } },
+    "preconditions": { "type": "array" },
+    "testData": { "type": "object" },
+    "steps": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "expected": {},
+    "postcondition": { "type": "array" },
+    "dimensions": { "type": "object" },
+    "scenario": { "type": "string" },
+    "category": { "type": "string" }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "genType": { "const": "e2e" } }, "required": ["genType"] },
+      "then": { "required": ["route", "testIds"] }
+    },
+    {
+      "if": { "properties": { "genType": { "const": "api-e2e" } }, "required": ["genType"] },
+      "then": {
+        "required": ["api", "apiSteps"],
+        "properties": {
+          "apiSteps": { "type": "array", "minItems": 1 },
+          "refs": {
+            "properties": {
+              "screen": { "type": "string", "pattern": "^API-.*$" }
+            }
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": { "schemaVersion": { "const": 2 } },
+        "required": ["schemaVersion"]
+      },
+      "then": {
+        "required": ["testMatrix", "steps"],
+        "properties": {
+          "testMatrix": { "type": "array", "minItems": 1 },
+          "steps": { "type": "array", "minItems": 1 }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "coverage": {
+            "type": "array",
+            "contains": { "const": "accessibility" }
+          }
+        }
+      },
+      "then": { "required": ["a11y"] }
+    }
+  ]
+}

package/scripts/prepare-install.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+/**
+ * Runs on `npm install` / `pnpm install` when this package is a dependency.
+ * Skips build if dist already exists (e.g. packed tarball from npm publish).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const distEntry = path.join(root, 'dist', 'docs', 'cli', 'engines.js');
+
+if (fs.existsSync(distEntry)) {
+  process.exit(0);
+}
+
+const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+const result = spawnSync(npmCmd, ['run', 'build'], {
+  cwd: root,
+  stdio: 'inherit',
+  env: process.env,
+});
+
+process.exit(result.status === null ? 1 : result.status);