cabloy 5.1.97 → 5.1.99

package/.cabloy-version

@@ -1 +1 @@
-5.1.97
+5.1.99

package/.claude/hooks/contract-loop-gate.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { readFileSync, statSync, writeFileSync, existsSync } from 'node:fs';
+import { existsSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { spawnSync, type SpawnSyncReturns } from 'node:child_process';
 import os from 'node:os';
 import path from 'node:path';
@@ -21,6 +21,25 @@ interface SyncStateEntry {
   timestamp: number;
 }
 
+interface CommandPlan {
+  args: readonly string[];
+  display: string;
+}
+
+interface EditionConfig {
+  id: 'basic' | 'start';
+  label: string;
+  reverseVonaContentMarkers: readonly string[];
+  reverseAutoSyncCommands: readonly CommandPlan[];
+  reverseWebBuildCommand: string;
+}
+
+type ReverseSyncOutcome =
+  | { kind: 'not-applicable'; message: string }
+  | { kind: 'skipped'; message: string }
+  | { kind: 'success'; message: string }
+  | { kind: 'failure'; message: string };
+
 type SyncState = Record<string, SyncStateEntry>;
 
 const SCRIPT_FILE = fileURLToPath(import.meta.url);
@@ -45,13 +64,10 @@ const FORWARD_PATH_MARKERS = ['/controller/', '/dto/', '/entity/'];
 
 const FORWARD_CONTENT_MARKERS = ['@Web.', '@Api.field', '@Api.body', 'v.openapi(', '@Dto<'];
 
-const REVERSE_VONA_CONTENT_MARKERS = [
-  'zova-rest-cabloy-basic-admin',
+const SHARED_REVERSE_VONA_CONTENT_MARKERS = [
   'ZovaRender.',
   'tableActionRow(',
   'tableActionBulk(',
-  'ZovaRender.field(',
-  'ZovaRender.cell(',
 ];
 
 const REVERSE_ZOVA_PATH_MARKERS = ['/src/bean/', '/src/component/', '/src/.metadata/'];
@@ -64,6 +80,35 @@ const REVERSE_ZOVA_CONTENT_MARKERS = [
   '@Component<',
 ];
 
+const REVERSE_AUTO_SYNC_COMMANDS: readonly CommandPlan[] = [
+  { args: ['run', 'build:zova:admin'], display: 'npm run build:zova:admin' },
+  { args: ['run', 'deps:vona'], display: 'npm run deps:vona' },
+];
+
+const EDITION_CONFIGS: Record<'basic' | 'start', EditionConfig> = {
+  basic: {
+    id: 'basic',
+    label: 'Cabloy Basic',
+    reverseVonaContentMarkers: ['zova-rest-cabloy-basic-admin'],
+    reverseAutoSyncCommands: REVERSE_AUTO_SYNC_COMMANDS,
+    reverseWebBuildCommand: 'npm run build:zova:web',
+  },
+  start: {
+    id: 'start',
+    label: 'Cabloy Start',
+    reverseVonaContentMarkers: ['zova-rest-cabloy-start-admin'],
+    reverseAutoSyncCommands: REVERSE_AUTO_SYNC_COMMANDS,
+    reverseWebBuildCommand: 'npm run build:zova:web',
+  },
+};
+
+const ACTIVE_EDITION = resolveEdition();
+const FALLBACK_REVERSE_VONA_CONTENT_MARKERS = [
+  ...SHARED_REVERSE_VONA_CONTENT_MARKERS,
+  ...EDITION_CONFIGS.basic.reverseVonaContentMarkers,
+  ...EDITION_CONFIGS.start.reverseVonaContentMarkers,
+];
+
 function toPosixPath(value: string): string {
   return value.split(path.sep).join('/');
 }
@@ -78,6 +123,21 @@ function normalizePath(value?: string): string | null {
   }
 }
 
+function resolveEdition(): EditionConfig | null {
+  if (existsSync(path.resolve(ROOT, '__CABLOY_BASIC__'))) {
+    return EDITION_CONFIGS.basic;
+  }
+  if (existsSync(path.resolve(ROOT, '__CABLOY_START__'))) {
+    return EDITION_CONFIGS.start;
+  }
+  return null;
+}
+
+function getReverseVonaContentMarkers(edition: EditionConfig | null): readonly string[] {
+  if (!edition) return FALLBACK_REVERSE_VONA_CONTENT_MARKERS;
+  return [...SHARED_REVERSE_VONA_CONTENT_MARKERS, ...edition.reverseVonaContentMarkers];
+}
+
 function isCodeFile(filePath: string): boolean {
   return TARGET_PATTERNS.some(([prefix, suffix]) => filePath.includes(prefix) && filePath.endsWith(suffix));
 }
@@ -98,8 +158,12 @@ function detectForward(filePath: string, content: string): string | null {
   return null;
 }
 
-function detectReverse(filePath: string, content: string): string | null {
-  if (filePath.includes('/vona/src/') && containsAny(content, REVERSE_VONA_CONTENT_MARKERS)) {
+function detectReverse(
+  filePath: string,
+  content: string,
+  reverseVonaContentMarkers: readonly string[],
+): string | null {
+  if (filePath.includes('/vona/src/') && containsAny(content, reverseVonaContentMarkers)) {
     return 'Vona code is consuming frontend metadata or render resources.';
   }
   if (
@@ -112,10 +176,10 @@ function detectReverse(filePath: string, content: string): string | null {
   return null;
 }
 
-function analyze(filePath: string, content: string): AnalysisResult {
+function analyze(filePath: string, content: string, edition: EditionConfig | null): AnalysisResult {
   return {
     forwardReason: detectForward(filePath, content),
-    reverseReason: detectReverse(filePath, content),
+    reverseReason: detectReverse(filePath, content, getReverseVonaContentMarkers(edition)),
   };
 }
 
@@ -180,9 +244,9 @@ function markAutoSync(filePath: string): void {
   saveState(state);
 }
 
-function runNpm(args: string[]): SpawnSyncReturns<string> {
+function runNpm(args: readonly string[]): SpawnSyncReturns<string> {
   const command = process.platform === 'win32' ? 'npm.cmd' : 'npm';
-  return spawnSync(command, args, {
+  return spawnSync(command, [...args], {
     cwd: ROOT,
     encoding: 'utf8',
   });
@@ -205,22 +269,79 @@ function summarizeProcess(result: SpawnSyncReturns<string>): string {
   return `exit ${exitCode}: ${tail}`;
 }
 
-function autoSyncReverse(filePath: string): readonly [boolean, string] {
-  const buildResult = runNpm(['run', 'build:zova:admin']);
-  if (buildResult.status !== 0) {
-    return [false, `Auto-sync failed during \`npm run build:zova:admin\`: ${summarizeProcess(buildResult)}`];
+function autoSyncReverse(filePath: string, edition: EditionConfig): ReverseSyncOutcome {
+  for (const command of edition.reverseAutoSyncCommands) {
+    const result = runNpm(command.args);
+    if (result.status !== 0) {
+      return {
+        kind: 'failure',
+        message: `Auto-sync failed during \`${command.display}\`: ${summarizeProcess(result)}`,
+      };
+    }
+  }
+
+  markAutoSync(filePath);
+  const commands = edition.reverseAutoSyncCommands.map(command => `\`${command.display}\``).join(' and ');
+  return {
+    kind: 'success',
+    message: `Auto-sync ran ${commands} for this ${edition.label} reverse-chain edit.`,
+  };
+}
+
+function buildReverseGuidance(edition: EditionConfig | null): string {
+  if (!edition) {
+    return 'If backend tooling or backend metadata will consume this handoff, refresh generated metadata when applicable, resolve the active Cabloy edition marker before choosing the relevant Zova build and generated-output path, and then run `npm run deps:vona`.';
+  }
+
+  const autoSyncCommands = edition.reverseAutoSyncCommands
+    .map(command => `\`${command.display}\``)
+    .join(', then ');
+  return `If backend tooling or backend metadata will consume this handoff, refresh generated metadata when applicable, run ${autoSyncCommands}, and also run \`${edition.reverseWebBuildCommand}\` when the Web flavor is affected in this ${edition.label} repo.`;
+}
+
+function resolveReverseSyncOutcome(
+  filePath: string,
+  result: AnalysisResult,
+  edition: EditionConfig | null,
+): ReverseSyncOutcome {
+  if (!result.reverseReason) {
+    return {
+      kind: 'not-applicable',
+      message: '',
+    };
   }
 
-  const depsResult = runNpm(['run', 'deps:vona']);
-  if (depsResult.status !== 0) {
-    return [false, `Auto-sync failed during \`npm run deps:vona\`: ${summarizeProcess(depsResult)}`];
+  if (!isHighConfidenceReverseSource(filePath)) {
+    return {
+      kind: 'not-applicable',
+      message:
+        'Auto-sync did not run because this reverse-chain signal came from the consumer side rather than a high-confidence frontend source edit.',
+    };
   }
 
-  markAutoSync(filePath);
-  return [true, 'Auto-sync ran `npm run build:zova:admin` and `npm run deps:vona` for this reverse-chain edit.'];
+  if (shouldSkipAutoSync(filePath)) {
+    return {
+      kind: 'skipped',
+      message: 'Auto-sync skipped because the same reverse-source edit was already synced recently in this repo.',
+    };
+  }
+
+  if (!edition) {
+    return {
+      kind: 'not-applicable',
+      message:
+        'Auto-sync did not run because the active Cabloy edition marker could not be resolved for this repo.',
+    };
+  }
+
+  return autoSyncReverse(filePath, edition);
 }
 
-function buildMessages(filePath: string, result: AnalysisResult): string {
+function buildMessages(
+  result: AnalysisResult,
+  edition: EditionConfig | null,
+  reverseSyncOutcome: ReverseSyncOutcome,
+): string {
   const messages = ["Contract-loop gate: this change may affect Cabloy's bidirectional contract loop."];
 
   if (result.forwardReason) {
@@ -233,30 +354,15 @@ function buildMessages(filePath: string, result: AnalysisResult): string {
   }
 
   if (result.reverseReason) {
-    messages.push(
-      `Reverse chain: ${result.reverseReason} If backend tooling or backend metadata will consume this handoff, refresh generated metadata when applicable, run the relevant Zova build first, and then run \`npm run deps:vona\` for the Cabloy Basic path. Use \`npm run build:zova:admin\` for Admin changes, and also run \`npm run build:zova:web\` when the Web flavor is affected.`,
-    );
-    if (isHighConfidenceReverseSource(filePath)) {
-      if (shouldSkipAutoSync(filePath)) {
-        messages.push('Auto-sync skipped because the same reverse-source edit was already synced recently in this repo.');
-      } else {
-        const [ok, detail] = autoSyncReverse(filePath);
-        messages.push(detail);
-        if (!ok) {
-          messages.push(
-            'Please review the failure before continuing. If generated artifacts already contain the expected changes but consumers still behave stale, suspect local dependency drift before making more source edits.',
-          );
-          return messages.join(' ');
-        }
-      }
-    } else {
+    messages.push(`Reverse chain: ${result.reverseReason} ${buildReverseGuidance(edition)}`);
+    if (reverseSyncOutcome.message) {
+      messages.push(reverseSyncOutcome.message);
+    }
+    if (reverseSyncOutcome.kind === 'failure') {
       messages.push(
-        'Auto-sync did not run because this reverse-chain signal came from the consumer side rather than a high-confidence frontend source edit.',
+        'Please review the failure before continuing. If generated artifacts already contain the expected changes but consumers still behave stale, suspect local dependency drift before making more source edits.',
       );
     }
-    messages.push(
-      'For Cabloy Start, apply the same reverse-chain logic but resolve the Start-specific flavor names and generated-output paths from the active Start repo before executing edition-specific steps.',
-    );
   }
 
   return messages.join(' ');
@@ -277,10 +383,11 @@ function runClaudeHook(): number {
   const content = readText(filePath);
   if (content === null) return 0;
 
-  const result = analyze(filePath, content);
+  const result = analyze(filePath, content, ACTIVE_EDITION);
   if (!hasSignal(result)) return 0;
 
-  const message = buildMessages(filePath, result);
+  const reverseSyncOutcome = resolveReverseSyncOutcome(filePath, result, ACTIVE_EDITION);
+  const message = buildMessages(result, ACTIVE_EDITION, reverseSyncOutcome);
   console.log(
     JSON.stringify({
       hookSpecificOutput: {

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # Changelog
 
+## 5.1.99
+
+### Features
+
+- Add dossier files to training records.
+- Derive dossier file policy from the file scene.
+
+### Improvements
+
+- Rename and standardize `QueryAutoLoad` helpers.
+- Use `QueryAutoLoad` for upload policy handling.
+- Simplify the contract loop hook.
+- Share Claude assets across editions.
+- Split permission cache beans for clearer responsibility.
+- Clarify permission action method names.
+- Align default permission guard evaluation.
+- Reuse derived upload policy state.
+- Streamline upload policy queries.
+- Derive image policy from the image scene.
+- Generate the file SDK and move policy state into the model.
+
+## 5.1.98
+
+### Features
+
+- Add `a-file` support.
+- Add CLI templates for `a-file`.
+- Add draft finalize flow for `a-image` direct uploads.
+- Add native direct-upload finalize flow.
+- Update the package with the latest feature enhancements.
+
+### Bug Fixes
+
+- Repair `a-image` type safety.
+- Support image delivery tokens.
+- Support private file download tokens.
+
+### Improvements
+
+- Clarify SSR bundle build hints.
+- Tighten SSR bundle error wording.
+- Simplify `a-file` upload and direct-upload contracts.
+- Simplify `a-image` upload flows and native variants.
+- Simplify the `a-image` resolve-view flow.
+- Tighten `a-image` provider option typing.
+- Remove the unused `a-image` failed status.
+- Optimize `a-image` draft pruning and response URL resolution.
+
 ## 5.1.97
 
 ### Improvements

package/CLAUDE.md

@@ -53,6 +53,8 @@ Before inventing a custom implementation path:
 - For frontend work, assume Cabloy Basic and Cabloy Start share a frontend engineering layer but may diverge in UI layer, frontend flavors, suite/module availability, SSR site baselines, project assets, and generated outputs.
 - For Zova frontend analysis, do not default to generic Vue reinterpretation first. Read the code through Zova’s controller / bean / IoC architecture before mapping it to Vue concepts.
 - For Zova source-reading or Vue-vs-Zova explanation tasks, start from the frontend reading guides and source-reading map in `cabloy-docs/frontend/` before doing framework-neutral reinterpretation.
+- For frontend async state that affects rendering or interaction across consumers, prefer model-owned `$useStateData(...)` over controller-managed fetch/cache state.
+- Default to establishing such query state during render. Use `disableSuspenseOnInit: true` only for relatively stable query-backed state when you want to skip the init-time `query.suspense()` kick; if strict readiness is needed later, wait explicitly at the interaction boundary.
 - Keep repo-wide AI rules in `CLAUDE.md` short and durable; put branching Zova analysis workflows in `.claude/skills/`.
 - For SSR theme-sensitive frontend work, detect the active edition marker and UI library before making assumptions. Cabloy Basic currently means DaisyUI + Tailwind CSS assumptions; Cabloy Start currently means Vuetify assumptions.
 - In Web SSR without cookie-backed theme resolution, do not treat server reads of `$theme.dark`, `$theme.darkMode`, or `$token` as final browser truth. Keep theme-sensitive SSR branching hydration-tolerant or defer final theme-sensitive decisions to the client.

package/cabloy-docs/.vitepress/config.mjs

@@ -98,6 +98,7 @@ const fullstackGroups = [
         text: 'Backend Metadata to Frontend Table Actions Source Reading Map',
         link: '/fullstack/backend-metadata-to-frontend-table-actions-source-reading-map',
       },
+      { text: 'Fullstack Image Workflow', link: '/fullstack/image-workflow' },
       { text: 'Backend OpenAPI to Frontend SDK', link: '/fullstack/openapi-to-sdk' },
       {
         text: 'Frontend Metadata Back to Backend',
@@ -231,6 +232,7 @@ export default defineConfig({
             { text: 'Event Guide', link: '/backend/event-guide' },
             { text: 'Logger Guide', link: '/backend/logger-guide' },
             { text: 'Upload Guide', link: '/backend/upload-guide' },
+            { text: 'Image Guide', link: '/backend/image-guide' },
             { text: 'Mail Guide', link: '/backend/mail-guide' },
             { text: 'Serialization Guide', link: '/backend/serialization-guide' },
           ],
@@ -330,6 +332,10 @@ export default defineConfig({
               text: 'Reading Zova for Vue Developers',
               link: '/frontend/reading-zova-for-vue-developers',
             },
+            {
+              text: 'State Architecture for Vue Developers',
+              link: '/frontend/state-architecture-for-vue-developers',
+            },
             {
               text: 'Zova vs Vue 3 Comparison',
               link: '/frontend/zova-vs-vue3-comparison',
@@ -415,6 +421,7 @@ export default defineConfig({
           items: [
             { text: 'Component Guide', link: '/frontend/component-guide' },
             { text: 'Form Guide', link: '/frontend/form-guide' },
+            { text: 'Image Guide', link: '/frontend/image-guide' },
             {
               text: 'Zova Form Under the Hood',
               link: '/frontend/zova-form-under-the-hood',
@@ -478,6 +485,10 @@ export default defineConfig({
               text: 'Resource Models & CRUD',
               items: [
                 { text: 'Model State Guide', link: '/frontend/model-state-guide' },
+                {
+                  text: '`$useStateData` Best Practices',
+                  link: '/frontend/use-state-data-best-practices',
+                },
                 {
                   text: 'Model Resource Owner Pattern',
                   link: '/frontend/model-resource-owner-pattern',

package/cabloy-docs/backend/controller-aop-guide.md

@@ -93,7 +93,6 @@ Typical jobs include:
 ```typescript
 @Passport.public()
 @Passport.activated(false)
-@Passport.userName({ name: 'admin' })
 @Passport.roleName({ name: 'admin' })
 @Passport.admin()
 ```