@shanyucoder/flowgrid 0.1.5 → 0.1.9

package/engines/registry-sync/run-registry-sync.mjs

@@ -0,0 +1,107 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import pc from 'picocolors';
+import { syncFeDesignRegistry } from './fe-design-sync.mjs';
+import { syncBeCapabilitiesRegistry } from './be-capabilities-sync.mjs';
+
+function packageRootFromMeta(metaUrl) {
+  return path.resolve(path.dirname(metaUrl), '../..');
+}
+
+async function rebuildArtifactGraphIndex(projectRoot) {
+  try {
+    const { loadEffectiveRepoConfig } = await import('../../dist/graph/config/load-config.js');
+    const { IndexStore } = await import('../../dist/graph/db/index-store.js');
+    const { loadRegistries, indexRegistries } = await import('../../dist/graph/registry/load-registries.js');
+    const { indexLexicons } = await import('../../dist/graph/lexicon/load-lexicon.js');
+    const cfg = loadEffectiveRepoConfig(projectRoot);
+    const store = new IndexStore(projectRoot);
+    store.transaction(() => {
+      const loaded = loadRegistries(projectRoot, cfg);
+      indexRegistries(store, loaded, projectRoot, cfg);
+      indexLexicons(store, projectRoot, cfg);
+    });
+    store.close();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {string[]} argv
+ * @param {{ packageRoot?: string, projectRoot?: string, config?: object }} ctx
+ */
+export async function runRegistrySync(argv = [], ctx = {}) {
+  const projectRoot = ctx.projectRoot ?? process.cwd();
+  const packageRoot = ctx.packageRoot ?? packageRootFromMeta(import.meta.url);
+  const dryRun = argv.includes('--dry-run');
+  const feOnly = argv.includes('--fe');
+  const beOnly = argv.includes('--be');
+
+  const configPath = path.join(projectRoot, '.flowgrid/config.json');
+  let config = ctx.config ?? {};
+  if (!ctx.config && fs.existsSync(configPath)) {
+    try {
+      config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    } catch {
+      config = {};
+    }
+  }
+
+  const feAdapter = config.frontend?.adapter;
+  const beAdapter = config.backend?.adapter;
+  const type = config.type ?? '';
+  const baseProfile = config.baseProfile ?? 'standard';
+
+  const runFe =
+    !beOnly &&
+    feAdapter &&
+    ['nuxt4', 'nextjs'].includes(feAdapter) &&
+    (feOnly || ['Frontend', 'Fullstack'].includes(type) || argv.includes('--fe'));
+  const runBe =
+    !feOnly &&
+    beAdapter &&
+    (beOnly || ['Backend', 'Fullstack'].includes(type) || argv.includes('--be'));
+
+  if (baseProfile === 'custom' && !argv.includes('--force')) {
+    console.log(
+      pc.yellow(
+        '[registry:sync] baseProfile=custom — skip FE scan (use build-template-code). Pass --force to scan anyway.',
+      ),
+    );
+    if (!runBe) return { code: 0 };
+  }
+
+  console.log(pc.cyan('\n=== flowgrid registry:sync ==='));
+  console.log(`  root: ${projectRoot}`);
+  if (dryRun) console.log(pc.magenta('  mode: dry-run'));
+
+  if (runFe) {
+    const fe = syncFeDesignRegistry(projectRoot, feAdapter, packageRoot, { dryRun });
+    console.log(pc.green('✔ FE design registry'));
+    console.log(
+      `    ${fe.report.registryPath}: ui=${fe.report.uiComponents} composables=${fe.report.composables} helpers=${fe.report.helpers} widgets=${fe.report.fieldWidgets} shells=${fe.report.shellsImplemented}`,
+    );
+  } else if (!beOnly) {
+    console.log(pc.gray('  (skip FE — no nuxt4/nextjs frontend in config)'));
+  }
+
+  if (runBe) {
+    const be = syncBeCapabilitiesRegistry(projectRoot, beAdapter, packageRoot, { dryRun });
+    console.log(pc.green('✔ BE capabilities registry'));
+    console.log(
+      `    ${be.report.registryPath}: entries=${be.report.capabilityKeys} middleware=${be.report.middleware}`,
+    );
+  } else if (!feOnly) {
+    console.log(pc.gray('  (skip BE — no backend adapter in config)'));
+  }
+
+  if (!dryRun && (runFe || runBe)) {
+    const ok = await rebuildArtifactGraphIndex(projectRoot);
+    if (ok) console.log(pc.gray('  + ArtifactGraph index rebuilt (.flowgrid/index.db)'));
+  }
+
+  console.log('');
+  return { code: 0 };
+}

package/engines/shared/e2e-output-layout.mjs

@@ -0,0 +1,68 @@
+import path from 'node:path';
+
+import {
+  API_E2E_ROOT_DIR_PARTS,
+  DEFAULT_E2E_ROOT_BACKEND_REL,
+  DEFAULT_E2E_ROOT_REL,
+  E2E_ROOT_DIR_PARTS,
+} from './flowgrid-e2e-root.mjs';
+
+/**
+ * Relative codegen + preflight trees from project root, given resolved automation root.
+ * @param {string} projectRoot
+ * @param {string | null | undefined} e2eRootAbs
+ * @param {{ projectType?: string }} [opts]
+ */
+export function codegenOutputLayout(projectRoot, e2eRootAbs, opts = {}) {
+  const resolvedProject = path.resolve(projectRoot);
+  let e2eAbs = e2eRootAbs ? path.resolve(e2eRootAbs) : null;
+  if (!e2eAbs) {
+    const rel =
+      opts.projectType === 'Backend' ? DEFAULT_E2E_ROOT_BACKEND_REL : DEFAULT_E2E_ROOT_REL;
+    e2eAbs = path.join(resolvedProject, rel);
+  }
+
+  const uiPrefix = path.relative(resolvedProject, e2eAbs).split(path.sep).join('/');
+  const defaultApi = path.join(...API_E2E_ROOT_DIR_PARTS);
+  let apiPrefix = defaultApi;
+
+  const uiNorm = uiPrefix.replace(/\\/g, '/');
+  if (uiNorm === 'tests') {
+    apiPrefix = defaultApi;
+  } else if (uiNorm === 'tests/e2e' || uiNorm.endsWith('/e2e')) {
+    const parent = path.dirname(uiNorm);
+    apiPrefix = parent === '.' ? 'api-e2e' : `${parent}/api-e2e`;
+  }
+
+  const allowedRelRoots = [
+    path.join(...E2E_ROOT_DIR_PARTS),
+    path.join(...API_E2E_ROOT_DIR_PARTS),
+    uiPrefix,
+    apiPrefix,
+  ]
+    .map((p) => p.replace(/\\/g, '/'))
+    .filter((p, i, arr) => p && arr.indexOf(p) === i);
+
+  return {
+    projectRoot: resolvedProject,
+    e2eRootAbs: e2eAbs,
+    uiPrefix,
+    apiPrefix,
+    allowedRelRoots,
+  };
+}
+
+/**
+ * Directories to scan for Playwright specs (UI + api-e2e).
+ * @param {string} projectRoot
+ * @param {string | null | undefined} e2eRootAbs
+ */
+export function playwrightScanRoots(projectRoot, e2eRootAbs) {
+  const layout = codegenOutputLayout(projectRoot, e2eRootAbs);
+  const roots = [layout.e2eRootAbs];
+  const apiAbs = path.join(layout.projectRoot, layout.apiPrefix);
+  if (apiAbs !== layout.e2eRootAbs) {
+    roots.push(apiAbs);
+  }
+  return roots;
+}

package/engines/shared/flowgrid-e2e-root.mjs

@@ -0,0 +1,19 @@
+/**
+ * Playwright automation roots (relative to code repo).
+ * testcase:gen (UI) → tests/e2e; testcase:gen:api → tests/api-e2e.
+ * audit e2e --e2e-root scans recursively for *.spec.ts / *.api.spec.ts.
+ * Distinct from tests-docs hub (YAML plan) and playwright.config (often repo root).
+ */
+export const E2E_ROOT_DIR_PARTS = ['tests', 'e2e'];
+export const API_E2E_ROOT_DIR_PARTS = ['tests', 'api-e2e'];
+
+export const DEFAULT_E2E_ROOT_REL = 'tests/e2e';
+/** Backend / API-hook lane: scan parent so api-e2e + optional UI specs both count. */
+export const DEFAULT_E2E_ROOT_BACKEND_REL = 'tests';
+
+/**
+ * @param {'Frontend' | 'Backend' | 'Fullstack' | string} projectType
+ */
+export function defaultE2eRootRel(projectType) {
+  return projectType === 'Backend' ? DEFAULT_E2E_ROOT_BACKEND_REL : DEFAULT_E2E_ROOT_REL;
+}

package/engines/shared/resolve-flowgrid-context.mjs

@@ -0,0 +1,176 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { ENV_TESTS_DOC, resolveTestsDocsRoot } from './flowgrid-tests-docs.mjs';
+
+export const ENV_DOCS_ROOT = 'FLOWGRID_DOCS_ROOT';
+export const ENV_PROJECT_ROOT = 'FLOWGRID_PROJECT_ROOT';
+export const ENV_E2E_ROOT = 'FLOWGRID_E2E_ROOT';
+
+/**
+ * @param {string} [cwd]
+ * @returns {object | null}
+ */
+export function loadFlowgridConfig(cwd = process.cwd()) {
+  const configPath = path.join(path.resolve(cwd), '.flowgrid', 'config.json');
+  if (!fs.existsSync(configPath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {string | null | undefined} relOrAbs
+ * @param {string} baseDir
+ * @returns {string | null}
+ */
+function resolveHubPath(relOrAbs, baseDir) {
+  if (!relOrAbs || typeof relOrAbs !== 'string' || !relOrAbs.trim()) return null;
+  const trimmed = relOrAbs.trim();
+  if (path.isAbsolute(trimmed)) return path.resolve(trimmed);
+  return path.resolve(baseDir, trimmed);
+}
+
+/**
+ * Docs hub pointer from config (FE lane first, then BE).
+ * @param {object | null | undefined} config
+ */
+export function docsRootFromConfig(config) {
+  if (!config || config.type === 'Document') return null;
+  const rel = config.frontend?.docsRoot ?? config.backend?.docsRoot ?? null;
+  return rel || null;
+}
+
+/**
+ * Tests-docs hub pointer from config.
+ * @param {object | null | undefined} config
+ */
+export function testsRootFromConfig(config) {
+  if (!config || config.type === 'Test') return null;
+  const rel = config.frontend?.testsRoot ?? config.backend?.testsRoot ?? null;
+  return rel || null;
+}
+
+/**
+ * E2e automation root from config.
+ * @param {object | null | undefined} config
+ */
+export function e2eRootFromConfig(config) {
+  if (!config) return null;
+  const rel = config.frontend?.e2eRoot ?? config.backend?.e2eRoot ?? null;
+  return rel || null;
+}
+
+/**
+ * Strip hub path flags from argv for downstream engines.
+ * @param {string[]} argv
+ * @returns {{ argv: string[]; docsRoot: string | null; testsDocs: string | null; e2eRoot: string | null; projectRoot: string | null }}
+ */
+export function extractFlowgridPathFlags(argv, baseDir = process.cwd()) {
+  const out = [];
+  let docsRoot = null;
+  let testsDocs = null;
+  let e2eRoot = null;
+  let projectRoot = null;
+  const cwd = path.resolve(baseDir);
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--docs-root' && argv[i + 1]) {
+      docsRoot = path.resolve(cwd, argv[++i]);
+      continue;
+    }
+    if (arg === '--tests-docs' && argv[i + 1]) {
+      testsDocs = path.resolve(cwd, argv[++i]);
+      continue;
+    }
+    if (arg === '--e2e-root' && argv[i + 1]) {
+      e2eRoot = path.resolve(cwd, argv[++i]);
+      continue;
+    }
+    if (arg === '--project-root' && argv[i + 1]) {
+      projectRoot = path.resolve(cwd, argv[++i]);
+      continue;
+    }
+    out.push(arg);
+  }
+
+  return { argv: out, docsRoot, testsDocs, e2eRoot, projectRoot };
+}
+
+/**
+ * Resolve docs hub absolute path.
+ * Priority: CLI --docs-root → FLOWGRID_DOCS_ROOT → config frontend|backend.docsRoot → Document type = cwd.
+ *
+ * @param {{ cwd?: string; config?: object | null; argv?: string[]; env?: NodeJS.ProcessEnv }} [opts]
+ * @returns {{ docsRoot: string | null; argv: string[]; projectRoot: string }}
+ */
+export function resolveFlowgridContext(opts = {}) {
+  const cwd = path.resolve(opts.cwd ?? process.cwd());
+  const env = opts.env ?? process.env;
+  const config = opts.config !== undefined ? opts.config : loadFlowgridConfig(cwd);
+  const extracted = extractFlowgridPathFlags(opts.argv ?? [], cwd);
+
+  const projectRoot = extracted.projectRoot
+    ?? (env[ENV_PROJECT_ROOT] ? path.resolve(env[ENV_PROJECT_ROOT]) : cwd);
+
+  let docsRoot = extracted.docsRoot;
+  if (!docsRoot && env[ENV_DOCS_ROOT]) {
+    docsRoot = path.resolve(env[ENV_DOCS_ROOT]);
+  }
+  if (!docsRoot && config?.type === 'Document') {
+    docsRoot = projectRoot;
+  }
+  if (!docsRoot) {
+    const rel = docsRootFromConfig(config);
+    docsRoot = resolveHubPath(rel, projectRoot);
+  }
+
+  let testsDocs = extracted.testsDocs ?? resolveTestsDocsRoot(null);
+  if (!testsDocs) {
+    const rel = testsRootFromConfig(config);
+    testsDocs = resolveHubPath(rel, projectRoot);
+  }
+
+  let e2eRoot = extracted.e2eRoot;
+  if (!e2eRoot && env[ENV_E2E_ROOT]) {
+    e2eRoot = path.resolve(env[ENV_E2E_ROOT]);
+  }
+  if (!e2eRoot) {
+    const rel = e2eRootFromConfig(config);
+    e2eRoot = resolveHubPath(rel, projectRoot);
+  }
+
+  return {
+    projectRoot,
+    docsRoot,
+    testsDocs,
+    e2eRoot,
+    argv: extracted.argv,
+    config,
+  };
+}
+
+/**
+ * @param {{ cwd?: string; config?: object | null; argv?: string[]; env?: NodeJS.ProcessEnv }} [opts]
+ * @returns {string | null}
+ */
+export function resolveDocsRoot(opts = {}) {
+  return resolveFlowgridContext(opts).docsRoot;
+}
+
+/**
+ * Apply resolved hub env for child processes (only sets when value known).
+ * @param {ReturnType<typeof resolveFlowgridContext>} ctx
+ * @param {NodeJS.ProcessEnv} [base]
+ */
+export function flowgridContextToEnv(ctx, base = {}) {
+  const env = { ...base };
+  if (ctx.docsRoot) env[ENV_DOCS_ROOT] = ctx.docsRoot;
+  if (ctx.testsDocs) env[ENV_TESTS_DOC] = ctx.testsDocs;
+  if (ctx.e2eRoot) env[ENV_E2E_ROOT] = ctx.e2eRoot;
+  env[ENV_PROJECT_ROOT] = ctx.projectRoot;
+  return env;
+}

package/engines/spec/lib/audit-api-gaps.mjs

@@ -2,7 +2,7 @@
 
 /**
  * audit-api-gaps.mjs
- * Zero-dependency static audit script for FlowGrid API Contracts (backend-api.bundle.yaml, backend-api-integration.yaml).
+ * Zero-dependency static audit for API contracts — target SSOT: `01-backend-spec.yaml` (legacy bundle-with-spec.api still parseable).
  * Ensures 100% adherence to API payload rules, SLA, async events, and resilience policies.
  */
 

package/engines/spec/lib/audit-bundle-gaps.mjs

@@ -13,13 +13,15 @@
  * pageType: list | create | detail | admin-crud | auth | change-password | public | not-found | error
  * If --type is omitted, script auto-detects from codegen.profile or design.shell.tag.
  *
- * Output: JSON with gaps[] (missing required) + confirms[] (optional, agent must ask member).
- * UX affordance checks (flowgrid-ux-common) merge in with category "ux" and codes UX_* / CONFIRM_UX_*.
+ * Output: JSON with gaps[] (missing required) + confirms[] (optional wizard) + warnings[] (quality — never blocks split).
+ * UX affordance: category "ux" (UX_* / CONFIRM_UX_*). DB tables: category "db" (CONFIRM_DB_*).
  */
 
 import fs from 'fs';
 import path from 'path';
+import { parse } from 'yaml';
 import { auditUxAffordance } from './audit-ux-affordance.mjs';
+import { auditDbTables, resolveBackendSpecForBundle } from './audit-db-tables.mjs';
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -111,6 +113,7 @@ function hasMutationActions(rawText) {
 function auditBundleContent(rawText, filePath, pageType) {
   const gaps = [];
   const confirms = [];
+  const warnings = [];
 
   function addGap(code, severity, fieldPath, message, suggestedFix) {
     gaps.push({ code, severity, type: 'gap', path: fieldPath, message, suggestedFix });
@@ -127,6 +130,17 @@ function auditBundleContent(rawText, filePath, pageType) {
     });
   }
 
+  function addWarning(code, fieldPath, message, suggestedFix) {
+    warnings.push({
+      code,
+      type: 'warning',
+      category: 'quality',
+      path: fieldPath,
+      message,
+      suggestedFix
+    });
+  }
+
   // =========================================================================
   // ALL PAGES — Required fields
   // =========================================================================
@@ -528,6 +542,51 @@ function auditBundleContent(rawText, filePath, pageType) {
   const uxGaps = gaps.filter((g) => g.category === 'ux').length;
   const uxConfirms = confirms.filter((c) => c.category === 'ux').length;
 
+  // =========================================================================
+  // Quality warnings (non-blocking — does not affect totalGaps for structure)
+  // =========================================================================
+
+  if (!has(rawText, 'successMetrics:')) {
+    addWarning(
+      'WARN_NO_SUCCESS_METRICS',
+      'successMetrics',
+      'successMetrics not declared — add when PO has measurable or qualitative targets.',
+      'Declare successMetrics: | with 1–3 bullets (see bundle-authoring.md).'
+    );
+  }
+
+  if (!has(rawText, 'nonGoals:')) {
+    addWarning(
+      'WARN_NO_NON_GOALS',
+      'nonGoals',
+      'nonGoals not declared — clarify out-of-scope for this screen/phase.',
+      'Declare nonGoals: | with explicit non-scope bullets.'
+    );
+  }
+
+  const placeholderCue = /\[[^\]]{8,}\]/;
+  if (has(rawText, 'summary:') && placeholderCue.test(rawText)) {
+    addWarning(
+      'WARN_SUMMARY_PLACEHOLDER',
+      'summary',
+      'Summary or related prose still contains bracket placeholders `[...]`.',
+      'Replace template brackets with real Vietnamese business copy before stakeholder sign-off.'
+    );
+  }
+
+  if (
+    has(rawText, 'messages:') &&
+    has(rawText, 'required:') &&
+    !hasAny(rawText, ['Trường này', 'bắt buộc', 'không được để trống', 'Vui lòng'])
+  ) {
+    addWarning(
+      'WARN_VALIDATION_MSG_GENERIC',
+      'design.sections',
+      'Validation messages may still use generic English — prefer explicit Vietnamese copy per field.',
+      'Set messages.* on each validated field (see bundle-authoring.md).'
+    );
+  }
+
   // =========================================================================
   // Result
   // =========================================================================
@@ -537,13 +596,15 @@ function auditBundleContent(rawText, filePath, pageType) {
     detectedType: pageType,
     totalGaps: gaps.length,
     totalConfirms: confirms.length,
+    totalWarnings: warnings.length,
     uxAffordanceGaps: uxGaps,
     uxAffordanceConfirms: uxConfirms,
     criticalGaps: gaps.filter(g => g.severity === 'critical').length,
     warningGaps: gaps.filter(g => g.severity === 'warning').length,
     infoGaps: gaps.filter(g => g.severity === 'info').length,
     gaps,
-    confirms
+    confirms,
+    warnings
   };
 }
 
@@ -579,4 +640,32 @@ if (!fs.existsSync(targetFile)) {
 const rawText = fs.readFileSync(targetFile, 'utf8');
 const pageType = typeArg || detectPageType(rawText);
 const report = auditBundleContent(rawText, targetFile, pageType);
+
+try {
+  const bundle = parse(rawText);
+  const backendResolved = resolveBackendSpecForBundle(targetFile, null);
+  const backendText =
+    backendResolved && fs.existsSync(backendResolved)
+      ? fs.readFileSync(backendResolved, 'utf8')
+      : '';
+  const dbReport = auditDbTables({
+    bundle,
+    backendText,
+    backendSpecFound: !!(backendResolved && fs.existsSync(backendResolved)),
+    filePath: targetFile,
+  });
+  report.confirms.push(...dbReport.confirms);
+  report.warnings.push(...dbReport.warnings);
+  report.totalConfirms = report.confirms.length;
+  report.totalWarnings = report.warnings.length;
+  report.dbTables = {
+    tables: dbReport.tables,
+    bindingCount: dbReport.bindings?.length ?? 0,
+    dbConfirms: dbReport.confirms?.length ?? 0,
+    backendSpec: backendResolved ? path.relative(process.cwd(), backendResolved) : null,
+  };
+} catch {
+  // YAML parse errors are handled elsewhere; skip DB pass
+}
+
 console.log(JSON.stringify(report, null, 2));