@carthooks/arcubase-cli 0.1.25 → 0.1.26

package/dist/runtime/execute.js

@@ -267,10 +267,10 @@ function renderDevSDKGenHelp() {
         '  - arcubase-admin dev sdk-gen --app-id <app_id> --out src/arcubase',
         '',
         'requirements:',
+        '  - every generated ingress must have a configured ingress.key; sdk-gen fails fast when keys are missing',
         '  - every generated field must have a configured field.key; sdk-gen fails fast when keys are missing',
-        '  - existing field.key values must be stable unique TypeScript identifiers',
-        '  - entity property names use entity.key when available, otherwise a stable entity<id> fallback',
-        '  - generated code accepts createArcubaseSdk({ baseURL, accessToken, refreshToken })',
+        '  - ingress.key and field.key values must be stable unique TypeScript identifiers',
+        '  - generated code accepts createArcubaseClient({ baseURL, accessToken, refreshToken }).ingress("<IngressKey>")',
     ].join('\n');
 }
 function resolveEndpoint(command, flags) {
@@ -1679,6 +1679,89 @@ function assertSDKGenFieldKeysPresent(entity) {
         ],
     });
 }
+function extractSDKGenIngressRefs(payload) {
+    const data = unwrapResponseData(payload);
+    const source = Array.isArray(data)
+        ? data
+        : isRecord(data) && Array.isArray(data.list)
+            ? data.list
+            : [];
+    return source.filter((item) => isRecord(item));
+}
+function ingressKeyOf(ingress) {
+    return typeof ingress.key === 'string' ? ingress.key.trim() : '';
+}
+function ingressHashIDOf(ingress) {
+    if (typeof ingress.hash_id === 'string' && ingress.hash_id.trim()) {
+        return ingress.hash_id.trim();
+    }
+    if (typeof ingress.hashId === 'string' && ingress.hashId.trim()) {
+        return ingress.hashId.trim();
+    }
+    return '';
+}
+function assertSDKGenIngressesReady(ingresses) {
+    if (ingresses.length === 0) {
+        throw new CLIError('SDK_GEN_NO_INGRESSES', 'sdk-gen could not find ingress definitions for this app', 2, {
+            operation: 'dev sdk-gen',
+            suggestions: ['create at least one access rule with a stable ingress.key before running sdk-gen'],
+        });
+    }
+    const seen = new Set();
+    const missingKey = [];
+    const missingHash = [];
+    const invalidKey = [];
+    const duplicateKey = [];
+    for (const ingress of ingresses) {
+        const key = ingressKeyOf(ingress);
+        if (!key) {
+            missingKey.push(ingress);
+            continue;
+        }
+        if (!/^[A-Za-z][A-Za-z0-9_]*$/.test(key)) {
+            invalidKey.push(key);
+        }
+        if (seen.has(key)) {
+            duplicateKey.push(key);
+        }
+        seen.add(key);
+        if (!ingressHashIDOf(ingress)) {
+            missingHash.push(ingress);
+        }
+    }
+    if (missingKey.length > 0) {
+        const preview = missingKey.slice(0, 8).map((ingress) => String(ingress.name ?? ingress.id ?? 'unnamed ingress'));
+        const suffix = missingKey.length > preview.length ? `, and ${missingKey.length - preview.length} more` : '';
+        throw new CLIError('SDK_GEN_INGRESS_KEY_REQUIRED', `missing ingress.key values: ${preview.join(', ')}${suffix}`, 2, {
+            operation: 'dev sdk-gen',
+            issues: missingKey.map((ingress) => ({
+                path: `ingress.${String(ingress.id ?? 'unknown')}.key`,
+                message: `ingress.key is required for ${String(ingress.name ?? ingress.id ?? 'unnamed ingress')}`,
+            })),
+            suggestions: [
+                'set stable ingress.key values in Arcubase admin before running sdk-gen',
+                'rerun arcubase-admin dev sdk-gen after ingress keys are complete',
+            ],
+        });
+    }
+    if (invalidKey.length > 0) {
+        throw new CLIError('SDK_GEN_INVALID_INGRESS_KEY', `invalid ingress.key values: ${invalidKey.join(', ')}`, 2, {
+            operation: 'dev sdk-gen',
+            suggestions: ['use TypeScript identifier keys such as publicEntry or customerPortal'],
+        });
+    }
+    if (duplicateKey.length > 0) {
+        throw new CLIError('SDK_GEN_DUPLICATE_INGRESS_KEY', `duplicate ingress.key values: ${duplicateKey.join(', ')}`, 2, {
+            operation: 'dev sdk-gen',
+        });
+    }
+    if (missingHash.length > 0) {
+        throw new CLIError('SDK_GEN_INGRESS_HASH_ID_REQUIRED', 'sdk-gen expected hash_id for every ingress definition', 2, {
+            operation: 'dev sdk-gen',
+            suggestions: ['upgrade Arcubase server so admin access-rule list returns hash_id'],
+        });
+    }
+}
 async function executeDevSDKGen(runtimeEnv, flags, fetchImpl) {
     validateDevSDKGenFlags(flags);
     const appId = flagValue(flags, 'app-id');
@@ -1705,7 +1788,7 @@ async function executeDevSDKGen(runtimeEnv, flags, fetchImpl) {
     if (entityRefs.length === 0) {
         throw new CLIError('SDK_GEN_NO_ENTITIES', 'sdk-gen could not find entities in app detail response', 2);
     }
-    const entities = [];
+    const ingresses = [];
     for (const entityRef of entityRefs) {
         const entityEndpoint = `/api/apps/${encodeURIComponent(appId)}/entity/${encodeURIComponent(entityRef.id)}`;
         const entityDetail = await requestJSON(runtimeEnv, 'GET', entityEndpoint, undefined, fetchImpl);
@@ -1714,12 +1797,21 @@ async function executeDevSDKGen(runtimeEnv, flags, fetchImpl) {
             throw new CLIError('SDK_GEN_INVALID_SCHEMA', 'sdk-gen expected entity detail response data', 2);
         }
         assertSDKGenFieldKeysPresent(entityPayload);
-        entities.push(entityPayload);
-    }
+        const ingressEndpoint = `/api/apps/${encodeURIComponent(appId)}/entity/${encodeURIComponent(entityRef.id)}/ingress`;
+        const ingressList = await requestJSON(runtimeEnv, 'GET', ingressEndpoint, undefined, fetchImpl);
+        const entityIngresses = extractSDKGenIngressRefs(ingressList.data).map((ingress) => ({
+            ...ingress,
+            hash_id: ingressHashIDOf(ingress),
+            key: ingressKeyOf(ingress),
+            entity: entityPayload,
+        }));
+        ingresses.push(...entityIngresses);
+    }
+    assertSDKGenIngressesReady(ingresses);
     const generated = generateArcubaseProjectSDK({
         id: resolveSDKGenAppId(appId, appPayload),
         name: typeof appPayload.name === 'string' ? appPayload.name : undefined,
-        entities,
+        ingresses,
     });
     const absoluteOutDir = path.resolve(process.cwd(), outDir);
     for (const file of generated.files) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carthooks/arcubase-cli",
-  "version": "0.1.25",
+  "version": "0.1.26",
   "description": "Arcubase runtime CLI for admin and user command execution",
   "type": "module",
   "main": "./dist/index.js",
@@ -31,7 +31,6 @@
     "docs:llms": "node -e \"\""
   },
   "dependencies": {
-    "@arcubase/code-gen": "^0.1.0",
     "@carthooks/client-ts": "0.8.0",
     "zod": "^4.4.3"
   },

package/sdk-dist/docs/runtime-reference/dev-sdk-gen.md

@@ -16,24 +16,26 @@ Workbench local ordinary-user codegen must not receive Arcubase admin tokens.
 It should use the BotWorks Host/JCode schema flow documented in
 `docs/design/workbench/03-workbench-vibe-coding-arcubase-codegen.md`.
 
-Generated code is key based. Application code uses stable `field.key` names, while generated runtime code converts those keys to internal numeric field ids.
-If any field is missing `field.key`, the command fails before generation and prints the missing fields. Set stable keys in Arcubase admin, then rerun the command.
+Generated code is ingress and key based. Application code selects a stable `ingress.key`, then uses stable `field.key` names. Generated runtime code converts those keys to the internal ingress id and numeric field ids.
+If any generated ingress is missing `ingress.key`, or any generated field is missing `field.key`, the command fails before generation and prints the missing keys. Set stable keys in Arcubase admin, then rerun the command.
 
 ```ts
-import { createArcubaseSdk } from './arcubase'
+import { createArcubaseClient } from './arcubase'
 
-const sdk = createArcubaseSdk({
+const client = createArcubaseClient({
   baseURL: 'https://team.example.arcubase.co/api',
   accessToken,
   refreshToken,
 })
 
-await sdk.story.create({
-  story: 'Once upon a time',
+const api = client.ingress('<IngressKey>')
+
+await api.create({
+  '<FieldKey>': value,
 })
 
-await sdk.story.update(rowId, {
-  story: 'Updated story',
+await api.update(rowId, {
+  '<FieldKey>': nextValue,
 })
 ```
 
@@ -44,9 +46,11 @@ Arcubase runtime credentials in browser code.
 
 Rules:
 
+- every generated ingress must have a configured `ingress.key`; sdk-gen does not invent fallback keys
 - every visible SDK field must have a configured `field.key`; sdk-gen does not invent fallback keys
-- existing `field.key` values must be stable unique TypeScript identifiers
+- existing `ingress.key` and `field.key` values must be stable unique TypeScript identifiers
+- `ingress.key` is the Web SDK entry contract and should not track display labels
 - `field.key` is a developer API contract and should not track display labels
-- entity property names use `entity.key` when available, otherwise a stable `entity<id>` fallback
+- generated Web code starts from `createArcubaseClient(...).ingress('<IngressKey>')`, not entity CRUD
 - row create/update/query code should use generated types, not raw field ids
 - rerun the command after schema changes and commit the regenerated source with the Web project

package/sdk-dist/generated/zod_registry.generated.ts

@@ -34,13 +34,13 @@ export const PermitUserScopeSchema: z.ZodTypeAny = z.lazy(() => z.object({ "data
 
 export const EntityIngressOptionsSchema: z.ZodTypeAny = z.lazy(() => z.object({ "i18n_name": I18NTextSchema.optional(), "list_options": PermitEntityListOptionsSchema.optional(), "policy": PermitPolicySchema.optional(), "user_scope": z.array(PermitUserScopeSchema).optional() }).strict())
 
-export const AppIngressBulkApplyItemVOSchema: z.ZodTypeAny = z.lazy(() => z.object({ "enabled": z.boolean().optional(), "name": z.string().optional(), "options": EntityIngressOptionsSchema.optional(), "rule_id": z.number().optional(), "table_id": z.number().optional(), "type": z.string().optional() }).strict())
+export const AppIngressBulkApplyItemVOSchema: z.ZodTypeAny = z.lazy(() => z.object({ "enabled": z.boolean().optional(), "key": z.string().optional(), "name": z.string().optional(), "options": EntityIngressOptionsSchema.optional(), "rule_id": z.number().optional(), "table_id": z.number().optional(), "type": z.string().optional() }).strict())
 
 export const AppIngressBulkApplyReqVOSchema: z.ZodTypeAny = z.lazy(() => z.object({ "dry_run": z.boolean().optional(), "items": z.array(AppIngressBulkApplyItemVOSchema).optional(), "mode": z.string().optional() }).strict())
 
-export const AppIngressCreateReqVOSchema: z.ZodTypeAny = z.lazy(() => z.object({ "enabled": z.boolean().optional(), "entity_id": z.number().optional(), "icon_name": z.string().optional(), "name": z.string().optional(), "options": EntityIngressOptionsSchema.optional(), "type": z.string().optional(), "url": z.string().optional() }).strict())
+export const AppIngressCreateReqVOSchema: z.ZodTypeAny = z.lazy(() => z.object({ "enabled": z.boolean().optional(), "entity_id": z.number().optional(), "icon_name": z.string().optional(), "key": z.string().optional(), "name": z.string().optional(), "options": EntityIngressOptionsSchema.optional(), "type": z.string().optional(), "url": z.string().optional() }).strict())
 
-export const AppIngressUpdateReqVOSchema: z.ZodTypeAny = z.lazy(() => z.object({ "enabled": z.boolean().optional(), "name": z.string().optional(), "options": EntityIngressOptionsSchema.optional(), "update": z.array(z.string()).optional() }).strict())
+export const AppIngressUpdateReqVOSchema: z.ZodTypeAny = z.lazy(() => z.object({ "enabled": z.boolean().optional(), "key": z.string().optional(), "name": z.string().optional(), "options": EntityIngressOptionsSchema.optional(), "update": z.array(z.string()).optional() }).strict())
 
 export const WidgetsTypeCodeSchema: z.ZodTypeAny = z.lazy(() => z.union([z.literal(1), z.literal(2)]))
 

package/sdk-dist/types/common.ts

@@ -50,6 +50,7 @@ export interface IngressItem {
   enabled?: boolean;
   i18n_name?: I18NText;
   id?: string;
+  key?: string;
   meta?: Record<string, any>;
   name?: string;
   type?: string;

package/sdk-dist/types/ingress.ts

@@ -23,7 +23,9 @@ export interface EntityIngress {
   app_id?: number;
   enabled?: boolean;
   entity_id?: number;
+  hash_id?: string;
   icon_name?: string;
+  key?: string;
   last_modified_by?: number;
   menu_group_id?: number;
   mode?: string;
@@ -64,6 +66,7 @@ export interface AppIngressBulkApplyItemRespVO {
 
 export interface AppIngressBulkApplyItemVO {
   enabled?: boolean;
+  key?: string;
   name?: string;
   options?: EntityIngressOptions;
   rule_id?: number;
@@ -88,6 +91,7 @@ export interface AppIngressCreateReqVO {
   enabled?: boolean;
   entity_id?: number;
   icon_name?: string;
+  key?: string;
   name?: string;
   options?: EntityIngressOptions;
   type?: string;
@@ -99,8 +103,10 @@ export interface AppIngressCreateRespVO {
   created_at?: number;
   enabled?: boolean;
   entity_id?: number;
+  hash_id?: string;
   icon_name?: string;
   id?: number;
+  key?: string;
   last_modified_by?: number;
   menu_group_id?: number;
   mode?: string;
@@ -117,8 +123,10 @@ export interface AppIngressDeleteRespVO {
   created_at?: number;
   enabled?: boolean;
   entity_id?: number;
+  hash_id?: string;
   icon_name?: string;
   id?: number;
+  key?: string;
   last_modified_by?: number;
   menu_group_id?: number;
   mode?: string;
@@ -135,8 +143,10 @@ export interface AppIngressGetByHashIDRespVO {
   created_at?: number;
   enabled?: boolean;
   entity_id?: number;
+  hash_id?: string;
   icon_name?: string;
   id?: number;
+  key?: string;
   last_modified_by?: number;
   menu_group_id?: number;
   mode?: string;
@@ -153,8 +163,10 @@ export interface AppIngressGetRespVO {
   created_at?: number;
   enabled?: boolean;
   entity_id?: number;
+  hash_id?: string;
   icon_name?: string;
   id?: number;
+  key?: string;
   last_modified_by?: number;
   menu_group_id?: number;
   mode?: string;
@@ -176,6 +188,7 @@ export interface AppIngressUpdateBlocksRespVO {
 
 export interface AppIngressUpdateReqVO {
   enabled?: boolean;
+  key?: string;
   name?: string;
   options?: EntityIngressOptions;
   update?: string[];
@@ -186,8 +199,10 @@ export interface AppIngressUpdateRespVO {
   created_at?: number;
   enabled?: boolean;
   entity_id?: number;
+  hash_id?: string;
   icon_name?: string;
   id?: number;
+  key?: string;
   last_modified_by?: number;
   menu_group_id?: number;
   mode?: string;

package/sdk-dist/types/user-action.ts

@@ -709,6 +709,7 @@ export interface IngressRespVO {
   has_admin?: boolean;
   id?: number;
   ingress?: {
+    key?: string;
     meta?: Record<string, any>;
     name?: string;
   };

package/src/generated/zod_registry.generated.ts

@@ -34,13 +34,13 @@ export const PermitUserScopeSchema: z.ZodTypeAny = z.lazy(() => z.object({ "data
 
 export const EntityIngressOptionsSchema: z.ZodTypeAny = z.lazy(() => z.object({ "i18n_name": I18NTextSchema.optional(), "list_options": PermitEntityListOptionsSchema.optional(), "policy": PermitPolicySchema.optional(), "user_scope": z.array(PermitUserScopeSchema).optional() }).strict())
 
-export const AppIngressBulkApplyItemVOSchema: z.ZodTypeAny = z.lazy(() => z.object({ "enabled": z.boolean().optional(), "name": z.string().optional(), "options": EntityIngressOptionsSchema.optional(), "rule_id": z.number().optional(), "table_id": z.number().optional(), "type": z.string().optional() }).strict())
+export const AppIngressBulkApplyItemVOSchema: z.ZodTypeAny = z.lazy(() => z.object({ "enabled": z.boolean().optional(), "key": z.string().optional(), "name": z.string().optional(), "options": EntityIngressOptionsSchema.optional(), "rule_id": z.number().optional(), "table_id": z.number().optional(), "type": z.string().optional() }).strict())
 
 export const AppIngressBulkApplyReqVOSchema: z.ZodTypeAny = z.lazy(() => z.object({ "dry_run": z.boolean().optional(), "items": z.array(AppIngressBulkApplyItemVOSchema).optional(), "mode": z.string().optional() }).strict())
 
-export const AppIngressCreateReqVOSchema: z.ZodTypeAny = z.lazy(() => z.object({ "enabled": z.boolean().optional(), "entity_id": z.number().optional(), "icon_name": z.string().optional(), "name": z.string().optional(), "options": EntityIngressOptionsSchema.optional(), "type": z.string().optional(), "url": z.string().optional() }).strict())
+export const AppIngressCreateReqVOSchema: z.ZodTypeAny = z.lazy(() => z.object({ "enabled": z.boolean().optional(), "entity_id": z.number().optional(), "icon_name": z.string().optional(), "key": z.string().optional(), "name": z.string().optional(), "options": EntityIngressOptionsSchema.optional(), "type": z.string().optional(), "url": z.string().optional() }).strict())
 
-export const AppIngressUpdateReqVOSchema: z.ZodTypeAny = z.lazy(() => z.object({ "enabled": z.boolean().optional(), "name": z.string().optional(), "options": EntityIngressOptionsSchema.optional(), "update": z.array(z.string()).optional() }).strict())
+export const AppIngressUpdateReqVOSchema: z.ZodTypeAny = z.lazy(() => z.object({ "enabled": z.boolean().optional(), "key": z.string().optional(), "name": z.string().optional(), "options": EntityIngressOptionsSchema.optional(), "update": z.array(z.string()).optional() }).strict())
 
 export const WidgetsTypeCodeSchema: z.ZodTypeAny = z.lazy(() => z.union([z.literal(1), z.literal(2)]))