@carthooks/arcubase-cli 0.1.0 → 0.1.2

package/bundle/arcubase-admin.mjs

@@ -94,6 +94,7 @@ function loadRuntimeEnv(scope, env = process.env) {
     ARCUBASE_BASE_URL: requiredValue(env, scope, "ARCUBASE_BASE_URL"),
     ARCUBASE_TENANT_ID: requiredValue(env, scope, "ARCUBASE_TENANT_ID"),
     ARCUBASE_ACCESS_TOKEN: requiredValue(env, scope, "ARCUBASE_ACCESS_TOKEN"),
+    ARCUBASE_HOST: optionalValue(env, scope, "ARCUBASE_HOST"),
     ARCUBASE_TRACE_ID: optionalValue(env, scope, "ARCUBASE_TRACE_ID"),
     ARCUBASE_SUBJECT_TYPE: optionalValue(env, scope, "ARCUBASE_SUBJECT_TYPE"),
     ARCUBASE_SUBJECT_ID: optionalValue(env, scope, "ARCUBASE_SUBJECT_ID"),
@@ -107,13 +108,26 @@ function buildRequestHeaders(env) {
     Authorization: `Bearer ${env.ARCUBASE_ACCESS_TOKEN}`,
     "X-Tenant-Id": env.ARCUBASE_TENANT_ID
   };
+  if (env.ARCUBASE_HOST && env.ARCUBASE_HOST.trim() !== "") {
+    headers["X-Host"] = env.ARCUBASE_HOST;
+  }
   if (env.ARCUBASE_TRACE_ID) {
     headers["X-Trace-Id"] = env.ARCUBASE_TRACE_ID;
   }
   return headers;
 }
+function normalizeExternalEndpoint(endpoint) {
+  const trimmed = endpoint.trim();
+  if (trimmed === "/api") {
+    return "/";
+  }
+  if (trimmed.startsWith("/api/")) {
+    return trimmed.slice(4);
+  }
+  return trimmed;
+}
 function buildURL(baseURL, endpoint, query) {
-  const url = new URL(endpoint, baseURL.endsWith("/") ? baseURL : `${baseURL}/`);
+  const url = new URL(normalizeExternalEndpoint(endpoint), baseURL.endsWith("/") ? baseURL : `${baseURL}/`);
   if (query) {
     for (const [key, value] of Object.entries(query)) {
       if (value === void 0 || value === null) continue;
@@ -9711,7 +9725,7 @@ function renderCommandHelp(scope, moduleName, commandName) {
   return [
     `${scope === "admin" ? "arcubase-admin" : "arcubase"} ${moduleName} ${commandName}`,
     `method: ${command.method}`,
-    `endpoint: ${command.endpoint}`,
+    `endpoint: ${normalizeExternalEndpoint(command.endpoint)}`,
     command.requestType ? `body: ${command.requestType} via --body-file` : "body: none",
     command.endpointParams.length ? `path flags: ${command.endpointParams.map((item) => `--${item.replace(/_/g, "-")}`).join(", ")}` : "path flags: none",
     command.scalarParams.length ? `scalar flags: ${command.scalarParams.map((item) => `--${item.name.replace(/([A-Z])/g, "-$1").toLowerCase()}`).join(", ")}` : "scalar flags: none"
@@ -9777,7 +9791,7 @@ async function executeCLI(scope, argv, env = loadRuntimeEnv(scope), fetchImpl =
   if (!command) {
     throw new CLIError("UNKNOWN_COMMAND", `unknown command: ${moduleName} ${commandName}`, 2);
   }
-  const endpoint = resolveEndpoint(command.endpoint, parsed.flags);
+  const endpoint = normalizeExternalEndpoint(resolveEndpoint(command.endpoint, parsed.flags));
   const scalarQuery = buildScalarQuery(command, parsed.flags);
   const fileQuery = loadQueryFromFlags(parsed.flags);
   const query = { ...scalarQuery ?? {}, ...fileQuery ?? {} };

package/bundle/arcubase.mjs

@@ -94,6 +94,7 @@ function loadRuntimeEnv(scope, env = process.env) {
     ARCUBASE_BASE_URL: requiredValue(env, scope, "ARCUBASE_BASE_URL"),
     ARCUBASE_TENANT_ID: requiredValue(env, scope, "ARCUBASE_TENANT_ID"),
     ARCUBASE_ACCESS_TOKEN: requiredValue(env, scope, "ARCUBASE_ACCESS_TOKEN"),
+    ARCUBASE_HOST: optionalValue(env, scope, "ARCUBASE_HOST"),
     ARCUBASE_TRACE_ID: optionalValue(env, scope, "ARCUBASE_TRACE_ID"),
     ARCUBASE_SUBJECT_TYPE: optionalValue(env, scope, "ARCUBASE_SUBJECT_TYPE"),
     ARCUBASE_SUBJECT_ID: optionalValue(env, scope, "ARCUBASE_SUBJECT_ID"),
@@ -107,13 +108,26 @@ function buildRequestHeaders(env) {
     Authorization: `Bearer ${env.ARCUBASE_ACCESS_TOKEN}`,
     "X-Tenant-Id": env.ARCUBASE_TENANT_ID
   };
+  if (env.ARCUBASE_HOST && env.ARCUBASE_HOST.trim() !== "") {
+    headers["X-Host"] = env.ARCUBASE_HOST;
+  }
   if (env.ARCUBASE_TRACE_ID) {
     headers["X-Trace-Id"] = env.ARCUBASE_TRACE_ID;
   }
   return headers;
 }
+function normalizeExternalEndpoint(endpoint) {
+  const trimmed = endpoint.trim();
+  if (trimmed === "/api") {
+    return "/";
+  }
+  if (trimmed.startsWith("/api/")) {
+    return trimmed.slice(4);
+  }
+  return trimmed;
+}
 function buildURL(baseURL, endpoint, query) {
-  const url = new URL(endpoint, baseURL.endsWith("/") ? baseURL : `${baseURL}/`);
+  const url = new URL(normalizeExternalEndpoint(endpoint), baseURL.endsWith("/") ? baseURL : `${baseURL}/`);
   if (query) {
     for (const [key, value] of Object.entries(query)) {
       if (value === void 0 || value === null) continue;
@@ -9711,7 +9725,7 @@ function renderCommandHelp(scope, moduleName, commandName) {
   return [
     `${scope === "admin" ? "arcubase-admin" : "arcubase"} ${moduleName} ${commandName}`,
     `method: ${command.method}`,
-    `endpoint: ${command.endpoint}`,
+    `endpoint: ${normalizeExternalEndpoint(command.endpoint)}`,
     command.requestType ? `body: ${command.requestType} via --body-file` : "body: none",
     command.endpointParams.length ? `path flags: ${command.endpointParams.map((item) => `--${item.replace(/_/g, "-")}`).join(", ")}` : "path flags: none",
     command.scalarParams.length ? `scalar flags: ${command.scalarParams.map((item) => `--${item.name.replace(/([A-Z])/g, "-$1").toLowerCase()}`).join(", ")}` : "scalar flags: none"
@@ -9777,7 +9791,7 @@ async function executeCLI(scope, argv, env = loadRuntimeEnv(scope), fetchImpl =
   if (!command) {
     throw new CLIError("UNKNOWN_COMMAND", `unknown command: ${moduleName} ${commandName}`, 2);
   }
-  const endpoint = resolveEndpoint(command.endpoint, parsed.flags);
+  const endpoint = normalizeExternalEndpoint(resolveEndpoint(command.endpoint, parsed.flags));
   const scalarQuery = buildScalarQuery(command, parsed.flags);
   const fileQuery = loadQueryFromFlags(parsed.flags);
   const query = { ...scalarQuery ?? {}, ...fileQuery ?? {} };

package/dist/runtime/env.d.ts

@@ -2,6 +2,7 @@ export type RuntimeEnv = {
     ARCUBASE_BASE_URL: string;
     ARCUBASE_TENANT_ID: string;
     ARCUBASE_ACCESS_TOKEN: string;
+    ARCUBASE_HOST?: string;
     ARCUBASE_TRACE_ID?: string;
     ARCUBASE_SUBJECT_TYPE?: string;
     ARCUBASE_SUBJECT_ID?: string;

package/dist/runtime/env.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/runtime/env.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAAG;IACvB,iBAAiB,EAAE,MAAM,CAAA;IACzB,kBAAkB,EAAE,MAAM,CAAA;IAC1B,qBAAqB,EAAE,MAAM,CAAA;IAC7B,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,yBAAyB,CAAC,EAAE,MAAM,CAAA;CACnC,CAAA;AAED,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,MAAM,CAAA;AAE9C,KAAK,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;AAqClD,wBAAgB,cAAc,CAAC,KAAK,EAAE,eAAe,EAAE,GAAG,GAAE,QAAsB,GAAG,UAAU,CAU9F"}
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/runtime/env.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAAG;IACvB,iBAAiB,EAAE,MAAM,CAAA;IACzB,kBAAkB,EAAE,MAAM,CAAA;IAC1B,qBAAqB,EAAE,MAAM,CAAA;IAC7B,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,yBAAyB,CAAC,EAAE,MAAM,CAAA;CACnC,CAAA;AAED,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,MAAM,CAAA;AAE9C,KAAK,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;AAqClD,wBAAgB,cAAc,CAAC,KAAK,EAAE,eAAe,EAAE,GAAG,GAAE,QAAsB,GAAG,UAAU,CAW9F"}

package/dist/runtime/env.js

@@ -34,6 +34,7 @@ export function loadRuntimeEnv(scope, env = process.env) {
         ARCUBASE_BASE_URL: requiredValue(env, scope, 'ARCUBASE_BASE_URL'),
         ARCUBASE_TENANT_ID: requiredValue(env, scope, 'ARCUBASE_TENANT_ID'),
         ARCUBASE_ACCESS_TOKEN: requiredValue(env, scope, 'ARCUBASE_ACCESS_TOKEN'),
+        ARCUBASE_HOST: optionalValue(env, scope, 'ARCUBASE_HOST'),
         ARCUBASE_TRACE_ID: optionalValue(env, scope, 'ARCUBASE_TRACE_ID'),
         ARCUBASE_SUBJECT_TYPE: optionalValue(env, scope, 'ARCUBASE_SUBJECT_TYPE'),
         ARCUBASE_SUBJECT_ID: optionalValue(env, scope, 'ARCUBASE_SUBJECT_ID'),

package/dist/runtime/execute.js

@@ -1,7 +1,7 @@
 import { parseCLIArgs, hasFlag, flagValue } from './argv.js';
 import { loadRuntimeEnv } from './env.js';
 import { CLIError } from './errors.js';
-import { buildRequestHeaders, buildURL } from './http.js';
+import { buildRequestHeaders, buildURL, normalizeExternalEndpoint } from './http.js';
 import { listModules, listModuleCommands, findCommand } from './command_registry.js';
 import { loadBodyFromFlags, loadQueryFromFlags } from './body_loader.js';
 import { getBodySchema, getTypeHints, getUnsupportedBodySchemaReason } from './zod_registry.js';
@@ -34,7 +34,7 @@ export function renderCommandHelp(scope, moduleName, commandName) {
     return [
         `${scope === 'admin' ? 'arcubase-admin' : 'arcubase'} ${moduleName} ${commandName}`,
         `method: ${command.method}`,
-        `endpoint: ${command.endpoint}`,
+        `endpoint: ${normalizeExternalEndpoint(command.endpoint)}`,
         command.requestType ? `body: ${command.requestType} via --body-file` : 'body: none',
         command.endpointParams.length ? `path flags: ${command.endpointParams.map((item) => `--${item.replace(/_/g, '-')}`).join(', ')}` : 'path flags: none',
         command.scalarParams.length ? `scalar flags: ${command.scalarParams.map((item) => `--${item.name.replace(/([A-Z])/g, '-$1').toLowerCase()}`).join(', ')}` : 'scalar flags: none',
@@ -93,7 +93,7 @@ export function summarizeCommand(scope, moduleName, commandName) {
         scope,
         commandPath: command.commandPath,
         method: command.method,
-        endpoint: command.endpoint,
+        endpoint: normalizeExternalEndpoint(command.endpoint),
         requestType: command.requestType,
         pathFlags: command.endpointParams,
         scalarFlags: command.scalarParams.map((item) => item.name.replace(/([A-Z])/g, '-$1').toLowerCase()),
@@ -118,7 +118,7 @@ export async function executeCLI(scope, argv, env = loadRuntimeEnv(scope), fetch
     if (!command) {
         throw new CLIError('UNKNOWN_COMMAND', `unknown command: ${moduleName} ${commandName}`, 2);
     }
-    const endpoint = resolveEndpoint(command.endpoint, parsed.flags);
+    const endpoint = normalizeExternalEndpoint(resolveEndpoint(command.endpoint, parsed.flags));
     const scalarQuery = buildScalarQuery(command, parsed.flags);
     const fileQuery = loadQueryFromFlags(parsed.flags);
     const query = { ...(scalarQuery ?? {}), ...(fileQuery ?? {}) };

package/dist/runtime/http.d.ts

@@ -1,4 +1,5 @@
 import type { RuntimeEnv } from './env.js';
-export declare function buildRequestHeaders(env: Pick<RuntimeEnv, 'ARCUBASE_ACCESS_TOKEN' | 'ARCUBASE_TENANT_ID' | 'ARCUBASE_TRACE_ID'>): Record<string, string>;
+export declare function buildRequestHeaders(env: Pick<RuntimeEnv, 'ARCUBASE_ACCESS_TOKEN' | 'ARCUBASE_TENANT_ID' | 'ARCUBASE_HOST' | 'ARCUBASE_TRACE_ID'>): Record<string, string>;
+export declare function normalizeExternalEndpoint(endpoint: string): string;
 export declare function buildURL(baseURL: string, endpoint: string, query?: Record<string, any>): string;
 //# sourceMappingURL=http.d.ts.map

package/dist/runtime/http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/runtime/http.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAE1C,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,IAAI,CAAC,UAAU,EAAE,uBAAuB,GAAG,oBAAoB,GAAG,mBAAmB,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CASvJ;AAED,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAS/F"}
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/runtime/http.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAE1C,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,IAAI,CAAC,UAAU,EAAE,uBAAuB,GAAG,oBAAoB,GAAG,eAAe,GAAG,mBAAmB,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAYzK;AAED,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CASlE;AAED,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAS/F"}

package/dist/runtime/http.js

@@ -3,13 +3,26 @@ export function buildRequestHeaders(env) {
         Authorization: `Bearer ${env.ARCUBASE_ACCESS_TOKEN}`,
         'X-Tenant-Id': env.ARCUBASE_TENANT_ID
     };
+    if (env.ARCUBASE_HOST && env.ARCUBASE_HOST.trim() !== '') {
+        headers['X-Host'] = env.ARCUBASE_HOST;
+    }
     if (env.ARCUBASE_TRACE_ID) {
         headers['X-Trace-Id'] = env.ARCUBASE_TRACE_ID;
     }
     return headers;
 }
+export function normalizeExternalEndpoint(endpoint) {
+    const trimmed = endpoint.trim();
+    if (trimmed === '/api') {
+        return '/';
+    }
+    if (trimmed.startsWith('/api/')) {
+        return trimmed.slice(4);
+    }
+    return trimmed;
+}
 export function buildURL(baseURL, endpoint, query) {
-    const url = new URL(endpoint, baseURL.endsWith('/') ? baseURL : `${baseURL}/`);
+    const url = new URL(normalizeExternalEndpoint(endpoint), baseURL.endsWith('/') ? baseURL : `${baseURL}/`);
     if (query) {
         for (const [key, value] of Object.entries(query)) {
             if (value === undefined || value === null)

package/dist/tests/bootstrap.test.js

@@ -15,6 +15,7 @@ test('loadRuntimeEnv returns normalized runtime env', () => {
         ARCUBASE_BASE_URL: 'http://example.com',
         ARCUBASE_TENANT_ID: 'tenant-1',
         ARCUBASE_ACCESS_TOKEN: 'token-1',
+        ARCUBASE_HOST: undefined,
         ARCUBASE_TRACE_ID: 'trace-1',
         ARCUBASE_SUBJECT_TYPE: undefined,
         ARCUBASE_SUBJECT_ID: undefined,
@@ -26,6 +27,7 @@ test('loadRuntimeEnv accepts admin-prefixed runtime env', () => {
         ARCUBASE_ADMIN_BASE_URL: ' https://admin.example.com ',
         ARCUBASE_ADMIN_TENANT_ID: ' tenant-admin ',
         ARCUBASE_ADMIN_ACCESS_TOKEN: ' token-admin ',
+        ARCUBASE_ADMIN_HOST: ' tenant-admin.arcubase.co ',
         ARCUBASE_ADMIN_SUBJECT_TYPE: ' system_admin ',
         ARCUBASE_ADMIN_SUBJECT_ID: ' user-admin ',
     });
@@ -33,6 +35,7 @@ test('loadRuntimeEnv accepts admin-prefixed runtime env', () => {
         ARCUBASE_BASE_URL: 'https://admin.example.com',
         ARCUBASE_TENANT_ID: 'tenant-admin',
         ARCUBASE_ACCESS_TOKEN: 'token-admin',
+        ARCUBASE_HOST: 'tenant-admin.arcubase.co',
         ARCUBASE_TRACE_ID: undefined,
         ARCUBASE_SUBJECT_TYPE: 'system_admin',
         ARCUBASE_SUBJECT_ID: 'user-admin',
@@ -44,6 +47,7 @@ test('loadRuntimeEnv accepts user-prefixed runtime env', () => {
         ARCUBASE_USER_BASE_URL: ' https://user.example.com ',
         ARCUBASE_USER_TENANT_ID: ' tenant-user ',
         ARCUBASE_USER_ACCESS_TOKEN: ' token-user ',
+        ARCUBASE_USER_HOST: ' tenant-user.arcubase.co ',
         ARCUBASE_USER_SUBJECT_TYPE: ' service_account ',
         ARCUBASE_USER_SUBJECT_ID: ' sa-user ',
     });
@@ -51,6 +55,7 @@ test('loadRuntimeEnv accepts user-prefixed runtime env', () => {
         ARCUBASE_BASE_URL: 'https://user.example.com',
         ARCUBASE_TENANT_ID: 'tenant-user',
         ARCUBASE_ACCESS_TOKEN: 'token-user',
+        ARCUBASE_HOST: 'tenant-user.arcubase.co',
         ARCUBASE_TRACE_ID: undefined,
         ARCUBASE_SUBJECT_TYPE: 'service_account',
         ARCUBASE_SUBJECT_ID: 'sa-user',

package/dist/tests/execute_validation.test.js

@@ -6,9 +6,10 @@ import path from 'path';
 import { executeCLI } from '../runtime/execute.js';
 import { CLIError } from '../runtime/errors.js';
 const env = {
-    ARCUBASE_BASE_URL: 'https://arcubase.example.com/api/',
+    ARCUBASE_BASE_URL: 'https://arcubase.example.com',
     ARCUBASE_TENANT_ID: 'tenant_1',
     ARCUBASE_ACCESS_TOKEN: 'tok',
+    ARCUBASE_HOST: 'tenant_1.arcubase.co',
     ARCUBASE_TRACE_ID: '',
     ARCUBASE_SUBJECT_TYPE: '',
     ARCUBASE_SUBJECT_ID: '',
@@ -35,7 +36,14 @@ test('admin save entity rejects invalid body file', async () => {
 });
 test('admin create entity executes with valid body file', async () => {
     const bodyFile = tempJSONFile({ name: '订单', parent: 0 });
-    const out = await executeCLI('admin', ['app', 'create-entity', '--id', 'app_1', '--body-file', bodyFile], env, async (url, init) => new Response(JSON.stringify({ ok: true, url, method: init?.method }), { status: 200 }));
+    const out = await executeCLI('admin', ['app', 'create-entity', '--id', 'app_1', '--body-file', bodyFile], env, async (url, init) => new Response(JSON.stringify({ ok: true, url, method: init?.method, host: init?.headers?.['X-Host'] }), { status: 200 }));
     assert.equal(out.kind, 'result');
     assert.equal(out.status, 200);
+    assert.equal(out.data.url, 'https://arcubase.example.com/apps/app_1/entities');
+    assert.equal(out.data.host, 'tenant_1.arcubase.co');
+});
+test('admin api-prefixed command executes against external root path', async () => {
+    const out = await executeCLI('admin', ['app-entity-share', 'get-app-entity-shares', '--app-id', 'app_1'], env, async (url, init) => new Response(JSON.stringify({ ok: true, url, method: init?.method }), { status: 200 }));
+    assert.equal(out.kind, 'result');
+    assert.equal(out.data.url, 'https://arcubase.example.com/apps/app_1/entity-shares');
 });

package/dist/tests/help.test.js

@@ -2,7 +2,7 @@ import test from 'node:test';
 import assert from 'node:assert/strict';
 import { executeCLI } from '../runtime/execute.js';
 const env = {
-    ARCUBASE_BASE_URL: 'https://arcubase.example.com/api/',
+    ARCUBASE_BASE_URL: 'https://arcubase.example.com',
     ARCUBASE_TENANT_ID: 'tenant_1',
     ARCUBASE_ACCESS_TOKEN: 'tok',
     ARCUBASE_TRACE_ID: '',
@@ -20,3 +20,9 @@ test('module help prints create-entity command', async () => {
     assert.equal(out.kind, 'help');
     assert.match(out.text, /create-entity/);
 });
+test('command help prints normalized external endpoint', async () => {
+    const out = await executeCLI('admin', ['app-entity-share', 'get-app-entity-shares', '--help'], env, async () => new Response('{}'));
+    assert.equal(out.kind, 'help');
+    assert.match(out.text, /endpoint: \/apps\/:app_id\/entity-shares/);
+    assert.doesNotMatch(out.text, /endpoint: \/api\//);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carthooks/arcubase-cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Arcubase runtime CLI for admin and user command execution",
   "type": "module",
   "main": "./dist/index.js",
@@ -39,8 +39,5 @@
     "ts-morph": "^25.0.1",
     "tsx": "^4.20.6",
     "typescript": "^5.3.3"
-  },
-  "publishConfig": {
-    "access": "public"
   }
 }

package/src/runtime/env.ts

@@ -2,6 +2,7 @@ export type RuntimeEnv = {
   ARCUBASE_BASE_URL: string
   ARCUBASE_TENANT_ID: string
   ARCUBASE_ACCESS_TOKEN: string
+  ARCUBASE_HOST?: string
   ARCUBASE_TRACE_ID?: string
   ARCUBASE_SUBJECT_TYPE?: string
   ARCUBASE_SUBJECT_ID?: string
@@ -52,6 +53,7 @@ export function loadRuntimeEnv(scope: RuntimeEnvScope, env: EnvInput = process.e
     ARCUBASE_BASE_URL: requiredValue(env, scope, 'ARCUBASE_BASE_URL'),
     ARCUBASE_TENANT_ID: requiredValue(env, scope, 'ARCUBASE_TENANT_ID'),
     ARCUBASE_ACCESS_TOKEN: requiredValue(env, scope, 'ARCUBASE_ACCESS_TOKEN'),
+    ARCUBASE_HOST: optionalValue(env, scope, 'ARCUBASE_HOST'),
     ARCUBASE_TRACE_ID: optionalValue(env, scope, 'ARCUBASE_TRACE_ID'),
     ARCUBASE_SUBJECT_TYPE: optionalValue(env, scope, 'ARCUBASE_SUBJECT_TYPE'),
     ARCUBASE_SUBJECT_ID: optionalValue(env, scope, 'ARCUBASE_SUBJECT_ID'),

package/src/runtime/execute.ts

@@ -1,7 +1,7 @@
 import { parseCLIArgs, hasFlag, flagValue } from './argv.js'
 import { loadRuntimeEnv, type RuntimeEnv } from './env.js'
 import { CLIError } from './errors.js'
-import { buildRequestHeaders, buildURL } from './http.js'
+import { buildRequestHeaders, buildURL, normalizeExternalEndpoint } from './http.js'
 import { listModules, listModuleCommands, findCommand, type CommandScope } from './command_registry.js'
 import { loadBodyFromFlags, loadQueryFromFlags } from './body_loader.js'
 import { getBodySchema, getTypeHints, getUnsupportedBodySchemaReason } from './zod_registry.js'
@@ -47,7 +47,7 @@ export function renderCommandHelp(scope: CommandScope, moduleName: string, comma
   return [
     `${scope === 'admin' ? 'arcubase-admin' : 'arcubase'} ${moduleName} ${commandName}`,
     `method: ${command.method}`,
-    `endpoint: ${command.endpoint}`,
+    `endpoint: ${normalizeExternalEndpoint(command.endpoint)}`,
     command.requestType ? `body: ${command.requestType} via --body-file` : 'body: none',
     command.endpointParams.length ? `path flags: ${command.endpointParams.map((item) => `--${item.replace(/_/g, '-')}`).join(', ')}` : 'path flags: none',
     command.scalarParams.length ? `scalar flags: ${command.scalarParams.map((item) => `--${item.name.replace(/([A-Z])/g, '-$1').toLowerCase()}`).join(', ')}` : 'scalar flags: none',
@@ -107,7 +107,7 @@ export function summarizeCommand(scope: CommandScope, moduleName: string, comman
     scope,
     commandPath: command.commandPath,
     method: command.method,
-    endpoint: command.endpoint,
+    endpoint: normalizeExternalEndpoint(command.endpoint),
     requestType: command.requestType,
     pathFlags: command.endpointParams,
     scalarFlags: command.scalarParams.map((item) => item.name.replace(/([A-Z])/g, '-$1').toLowerCase()),
@@ -135,7 +135,7 @@ export async function executeCLI(scope: CommandScope, argv: string[], env: Runti
     throw new CLIError('UNKNOWN_COMMAND', `unknown command: ${moduleName} ${commandName}`, 2)
   }
 
-  const endpoint = resolveEndpoint(command.endpoint, parsed.flags)
+  const endpoint = normalizeExternalEndpoint(resolveEndpoint(command.endpoint, parsed.flags))
   const scalarQuery = buildScalarQuery(command, parsed.flags)
   const fileQuery = loadQueryFromFlags(parsed.flags)
   const query = { ...(scalarQuery ?? {}), ...(fileQuery ?? {}) }

package/src/runtime/http.ts

@@ -1,18 +1,32 @@
 import type { RuntimeEnv } from './env.js'
 
-export function buildRequestHeaders(env: Pick<RuntimeEnv, 'ARCUBASE_ACCESS_TOKEN' | 'ARCUBASE_TENANT_ID' | 'ARCUBASE_TRACE_ID'>): Record<string, string> {
+export function buildRequestHeaders(env: Pick<RuntimeEnv, 'ARCUBASE_ACCESS_TOKEN' | 'ARCUBASE_TENANT_ID' | 'ARCUBASE_HOST' | 'ARCUBASE_TRACE_ID'>): Record<string, string> {
   const headers: Record<string, string> = {
     Authorization: `Bearer ${env.ARCUBASE_ACCESS_TOKEN}`,
     'X-Tenant-Id': env.ARCUBASE_TENANT_ID
   }
+  if (env.ARCUBASE_HOST && env.ARCUBASE_HOST.trim() !== '') {
+    headers['X-Host'] = env.ARCUBASE_HOST
+  }
   if (env.ARCUBASE_TRACE_ID) {
     headers['X-Trace-Id'] = env.ARCUBASE_TRACE_ID
   }
   return headers
 }
 
+export function normalizeExternalEndpoint(endpoint: string): string {
+  const trimmed = endpoint.trim()
+  if (trimmed === '/api') {
+    return '/'
+  }
+  if (trimmed.startsWith('/api/')) {
+    return trimmed.slice(4)
+  }
+  return trimmed
+}
+
 export function buildURL(baseURL: string, endpoint: string, query?: Record<string, any>): string {
-  const url = new URL(endpoint, baseURL.endsWith('/') ? baseURL : `${baseURL}/`)
+  const url = new URL(normalizeExternalEndpoint(endpoint), baseURL.endsWith('/') ? baseURL : `${baseURL}/`)
   if (query) {
     for (const [key, value] of Object.entries(query)) {
       if (value === undefined || value === null) continue

package/src/tests/bootstrap.test.ts

@@ -19,6 +19,7 @@ test('loadRuntimeEnv returns normalized runtime env', () => {
     ARCUBASE_BASE_URL: 'http://example.com',
     ARCUBASE_TENANT_ID: 'tenant-1',
     ARCUBASE_ACCESS_TOKEN: 'token-1',
+    ARCUBASE_HOST: undefined,
     ARCUBASE_TRACE_ID: 'trace-1',
     ARCUBASE_SUBJECT_TYPE: undefined,
     ARCUBASE_SUBJECT_ID: undefined,
@@ -31,6 +32,7 @@ test('loadRuntimeEnv accepts admin-prefixed runtime env', () => {
     ARCUBASE_ADMIN_BASE_URL: ' https://admin.example.com ',
     ARCUBASE_ADMIN_TENANT_ID: ' tenant-admin ',
     ARCUBASE_ADMIN_ACCESS_TOKEN: ' token-admin ',
+    ARCUBASE_ADMIN_HOST: ' tenant-admin.arcubase.co ',
     ARCUBASE_ADMIN_SUBJECT_TYPE: ' system_admin ',
     ARCUBASE_ADMIN_SUBJECT_ID: ' user-admin ',
   })
@@ -39,6 +41,7 @@ test('loadRuntimeEnv accepts admin-prefixed runtime env', () => {
     ARCUBASE_BASE_URL: 'https://admin.example.com',
     ARCUBASE_TENANT_ID: 'tenant-admin',
     ARCUBASE_ACCESS_TOKEN: 'token-admin',
+    ARCUBASE_HOST: 'tenant-admin.arcubase.co',
     ARCUBASE_TRACE_ID: undefined,
     ARCUBASE_SUBJECT_TYPE: 'system_admin',
     ARCUBASE_SUBJECT_ID: 'user-admin',
@@ -51,6 +54,7 @@ test('loadRuntimeEnv accepts user-prefixed runtime env', () => {
     ARCUBASE_USER_BASE_URL: ' https://user.example.com ',
     ARCUBASE_USER_TENANT_ID: ' tenant-user ',
     ARCUBASE_USER_ACCESS_TOKEN: ' token-user ',
+    ARCUBASE_USER_HOST: ' tenant-user.arcubase.co ',
     ARCUBASE_USER_SUBJECT_TYPE: ' service_account ',
     ARCUBASE_USER_SUBJECT_ID: ' sa-user ',
   })
@@ -59,6 +63,7 @@ test('loadRuntimeEnv accepts user-prefixed runtime env', () => {
     ARCUBASE_BASE_URL: 'https://user.example.com',
     ARCUBASE_TENANT_ID: 'tenant-user',
     ARCUBASE_ACCESS_TOKEN: 'token-user',
+    ARCUBASE_HOST: 'tenant-user.arcubase.co',
     ARCUBASE_TRACE_ID: undefined,
     ARCUBASE_SUBJECT_TYPE: 'service_account',
     ARCUBASE_SUBJECT_ID: 'sa-user',

package/src/tests/execute_validation.test.ts

@@ -7,9 +7,10 @@ import { executeCLI } from '../runtime/execute.js'
 import { CLIError } from '../runtime/errors.js'
 
 const env = {
-  ARCUBASE_BASE_URL: 'https://arcubase.example.com/api/',
+  ARCUBASE_BASE_URL: 'https://arcubase.example.com',
   ARCUBASE_TENANT_ID: 'tenant_1',
   ARCUBASE_ACCESS_TOKEN: 'tok',
+  ARCUBASE_HOST: 'tenant_1.arcubase.co',
   ARCUBASE_TRACE_ID: '',
   ARCUBASE_SUBJECT_TYPE: '',
   ARCUBASE_SUBJECT_ID: '',
@@ -43,8 +44,21 @@ test('admin create entity executes with valid body file', async () => {
     'admin',
     ['app', 'create-entity', '--id', 'app_1', '--body-file', bodyFile],
     env as any,
-    async (url, init) => new Response(JSON.stringify({ ok: true, url, method: init?.method }), { status: 200 })
+    async (url, init) => new Response(JSON.stringify({ ok: true, url, method: init?.method, host: (init?.headers as Record<string, string>)?.['X-Host'] }), { status: 200 })
   )
   assert.equal(out.kind, 'result')
   assert.equal(out.status, 200)
+  assert.equal(out.data.url, 'https://arcubase.example.com/apps/app_1/entities')
+  assert.equal(out.data.host, 'tenant_1.arcubase.co')
+})
+
+test('admin api-prefixed command executes against external root path', async () => {
+  const out = await executeCLI(
+    'admin',
+    ['app-entity-share', 'get-app-entity-shares', '--app-id', 'app_1'],
+    env as any,
+    async (url, init) => new Response(JSON.stringify({ ok: true, url, method: init?.method }), { status: 200 })
+  )
+  assert.equal(out.kind, 'result')
+  assert.equal(out.data.url, 'https://arcubase.example.com/apps/app_1/entity-shares')
 })

package/src/tests/help.test.ts

@@ -3,7 +3,7 @@ import assert from 'node:assert/strict'
 import { executeCLI } from '../runtime/execute.js'
 
 const env = {
-  ARCUBASE_BASE_URL: 'https://arcubase.example.com/api/',
+  ARCUBASE_BASE_URL: 'https://arcubase.example.com',
   ARCUBASE_TENANT_ID: 'tenant_1',
   ARCUBASE_ACCESS_TOKEN: 'tok',
   ARCUBASE_TRACE_ID: '',
@@ -23,3 +23,10 @@ test('module help prints create-entity command', async () => {
   assert.equal(out.kind, 'help')
   assert.match(out.text, /create-entity/)
 })
+
+test('command help prints normalized external endpoint', async () => {
+  const out = await executeCLI('admin', ['app-entity-share', 'get-app-entity-shares', '--help'], env as any, async () => new Response('{}'))
+  assert.equal(out.kind, 'help')
+  assert.match(out.text, /endpoint: \/apps\/:app_id\/entity-shares/)
+  assert.doesNotMatch(out.text, /endpoint: \/api\//)
+})