@lovrabet/cli-framework 1.0.4-beta.2 → 1.0.4

package/lib/service-tree/index.d.ts

@@ -1,4 +1,4 @@
-export type { NormalizedServiceTree, NormalizedServiceTreeCommand, NormalizedServiceTreeFlag, NormalizedServiceTreeTarget, ServiceTreeAppBinding, ServiceTreeArg, ServiceTreeCommand, ServiceTreeCompileInput, ServiceTreeDatasetResolver, ServiceTreeDatasetResolverInput, ServiceTreeExecutionPlan, ServiceTreeFlag, ServiceTreeManifest, ServiceTreeMapTo, ServiceTreeMapToObject, ServiceTreeMapToRule, ServiceTreeMapTransform, ServiceTreeMatch, ServiceTreeServiceInfo, ServiceTreeTarget, ServiceTreeTargetCommand, ServiceTreeTargetKind, ServiceTreeValidationIssue, ServiceTreeValidationReport, ServiceTreeValueType, } from "./types.js";
+export type { NormalizedServiceTree, NormalizedServiceTreeCommand, NormalizedServiceTreeFlag, NormalizedServiceTreeTarget, ServiceTreeAppBinding, ServiceTreeAppBindingInput, ServiceTreeArg, ServiceTreeArgInput, ServiceTreeAction, ServiceTreeCommand, ServiceTreeCompileInput, ServiceTreeDatasetResolver, ServiceTreeDatasetResolverInput, ServiceTreeExecutionPlan, ServiceTreeFlag, ServiceTreeFlagsInput, ServiceTreeManifest, ServiceTreeMapTo, ServiceTreeMapToObject, ServiceTreeMapToRule, ServiceTreeMapTransform, ServiceTreeMatch, ServiceTreeResource, ServiceTreeServiceInfo, ServiceTreeSimpleFlag, ServiceTreeTarget, ServiceTreeTargetCommand, ServiceTreeTargetKind, ServiceTreeValidationIssue, ServiceTreeValidationReport, ServiceTreeValueType, } from "./types.js";
 export { compileServiceTreeCommand } from "./compile.js";
 export { matchServiceTreeCommand } from "./match.js";
 export { normalizeServiceTreeManifest } from "./normalize.js";

package/lib/service-tree/normalize.js

@@ -1,35 +1,296 @@
 import { normalizeMapTo } from "./map-to.js";
 import { splitServiceTreePath, toKebabCase } from "./path.js";
 const DEFAULT_PROTOCOL = "lovrabet.service-tree/v1";
+const DEFAULT_VERSION = "1.0.0";
+const DEFAULT_APP_REF = "default";
 export function normalizeServiceTreeManifest(manifest) {
-    const serviceCode = manifest.service.code;
+    const service = normalizeServiceInfo(manifest);
+    const serviceCode = service.code;
+    const appBindings = normalizeAppBindings(manifest);
+    const defaultAppRef = resolveDefaultAppRef(manifest, appBindings);
+    const commands = [
+        ...normalizeLegacyCommands(manifest, serviceCode, defaultAppRef),
+        ...normalizeResourceCommands(manifest, serviceCode, defaultAppRef),
+    ];
     return {
         protocol: manifest.protocol || DEFAULT_PROTOCOL,
-        version: manifest.version,
-        service: { ...manifest.service },
-        appBindings: { ...(manifest.appBindings || {}) },
-        commands: manifest.commands.map((command) => {
-            const path = splitServiceTreePath(command.path);
-            const fullPath = path[0] === serviceCode ? path : [serviceCode, ...path];
-            const flags = (command.flags || []).map((flag) => ({
-                ...flag,
-                cliName: flag.cliName ? toKebabCase(flag.cliName) : toKebabCase(flag.name),
+        version: manifest.version || DEFAULT_VERSION,
+        service,
+        appBindings,
+        commands,
+    };
+}
+function normalizeServiceInfo(manifest) {
+    if (typeof manifest.service === "string") {
+        return {
+            code: manifest.service,
+            name: manifest.name,
+            description: manifest.description,
+        };
+    }
+    return {
+        ...manifest.service,
+        name: manifest.service.name || manifest.name,
+        description: manifest.service.description || manifest.description,
+    };
+}
+function normalizeAppBindings(manifest) {
+    const bindings = {};
+    if (manifest.appBindings) {
+        for (const [key, value] of Object.entries(manifest.appBindings)) {
+            bindings[key] = normalizeAppBinding(value);
+        }
+    }
+    if (manifest.apps) {
+        for (const [key, value] of Object.entries(manifest.apps)) {
+            bindings[key] = normalizeAppBinding(value);
+        }
+    }
+    if (manifest.app !== undefined && !bindings[DEFAULT_APP_REF]) {
+        bindings[DEFAULT_APP_REF] = normalizeAppBinding(manifest.app);
+    }
+    return bindings;
+}
+function normalizeAppBinding(input) {
+    if (typeof input !== "string")
+        return { ...input };
+    return input.startsWith("app-")
+        ? { appcode: input }
+        : { app: input };
+}
+function resolveDefaultAppRef(manifest, appBindings) {
+    if (manifest.app !== undefined)
+        return DEFAULT_APP_REF;
+    const keys = Object.keys(appBindings);
+    return keys.length === 1 ? keys[0] : undefined;
+}
+function normalizeLegacyCommands(manifest, serviceCode, defaultAppRef) {
+    return (manifest.commands || []).map((command) => normalizeCommand(command, serviceCode, defaultAppRef, manifest.defaults));
+}
+function normalizeResourceCommands(manifest, serviceCode, defaultAppRef) {
+    return flattenResources({
+        resources: manifest.resources || {},
+        serviceCode,
+        defaultAppRef,
+        path: [],
+        inherited: {
+            appRef: defaultAppRef,
+            defaults: manifest.defaults || {},
+        },
+    });
+}
+function flattenResources(input) {
+    const commands = [];
+    for (const [resourceCode, resource] of Object.entries(input.resources)) {
+        const path = [...input.path, resourceCode];
+        const inherited = {
+            appRef: resource.appRef || resource.app || input.inherited.appRef,
+            datasetCode: resource.datasetCode || input.inherited.datasetCode,
+            datatable: resource.datatable || resource.table || input.inherited.datatable,
+            defaults: {
+                ...input.inherited.defaults,
+                ...(resource.defaults || {}),
+                ...(resource.params || {}),
+            },
+        };
+        for (const [actionCode, action] of Object.entries(resource.actions || {})) {
+            commands.push(normalizeActionCommand({
+                serviceCode: input.serviceCode,
+                defaultAppRef: input.defaultAppRef,
+                path: [...path, actionCode],
+                resource,
+                action,
+                inherited,
             }));
-            return {
+        }
+        if (resource.resources) {
+            commands.push(...flattenResources({
+                resources: resource.resources,
+                serviceCode: input.serviceCode,
+                defaultAppRef: input.defaultAppRef,
                 path,
-                fullPath,
-                cliPath: fullPath.join(" "),
-                description: command.description,
-                risk: command.risk || "read",
-                args: command.args || [],
-                flags,
-                target: { ...command.target },
-                baseParams: {
-                    ...(command.target.params || {}),
-                    ...(command.params || {}),
-                },
-                mapTo: normalizeMapTo(command.mapTo, flags),
-            };
-        }),
+                inherited,
+            }));
+        }
+    }
+    return commands;
+}
+function normalizeActionCommand(input) {
+    const action = input.action;
+    const target = normalizeActionTarget(action, input.inherited);
+    const args = normalizeArgs(action.args);
+    const flags = normalizeFlags(action.flags);
+    const mapTo = normalizeMapInput(action.mapTo || action.map, args, flags);
+    return buildNormalizedCommand({
+        serviceCode: input.serviceCode,
+        path: input.path,
+        description: action.description,
+        risk: action.risk,
+        args,
+        flags,
+        target,
+        params: {
+            ...input.inherited.defaults,
+            ...(action.defaults || {}),
+            ...(action.params || {}),
+        },
+        mapTo,
+    });
+}
+function normalizeCommand(command, serviceCode, defaultAppRef, serviceDefaults) {
+    const args = normalizeArgs(command.args);
+    const flags = normalizeFlags(command.flags);
+    const mapTo = normalizeMapInput(command.mapTo || command.map, args, flags);
+    const target = {
+        ...command.target,
+        appRef: command.target.appRef || defaultAppRef,
     };
+    return buildNormalizedCommand({
+        serviceCode,
+        path: splitServiceTreePath(command.path),
+        description: command.description,
+        risk: command.risk,
+        args,
+        flags,
+        target,
+        params: {
+            ...(serviceDefaults || {}),
+            ...(command.defaults || {}),
+            ...(command.params || {}),
+        },
+        mapTo,
+    });
+}
+function buildNormalizedCommand(input) {
+    const fullPath = input.path[0] === input.serviceCode
+        ? input.path
+        : [input.serviceCode, ...input.path];
+    return {
+        path: input.path,
+        fullPath,
+        cliPath: fullPath.join(" "),
+        description: input.description,
+        risk: input.risk || inferRisk(input.target),
+        args: input.args,
+        flags: input.flags,
+        target: { ...input.target },
+        baseParams: {
+            ...(input.target.params || {}),
+            ...input.params,
+        },
+        mapTo: normalizeMapTo(input.mapTo, input.flags),
+    };
+}
+function normalizeActionTarget(action, inherited) {
+    if (typeof action.target === "object") {
+        return {
+            ...action.target,
+            appRef: action.target.appRef || action.appRef || action.app || inherited.appRef,
+            datasetCode: action.target.datasetCode || action.datasetCode || inherited.datasetCode,
+            datatable: action.target.datatable || action.datatable || action.table || inherited.datatable,
+            sqlCode: action.target.sqlCode || action.sqlCode,
+            bffCode: action.target.bffCode || action.bffCode,
+            bffId: action.target.bffId || action.bffId,
+            scriptName: action.target.scriptName || action.scriptName,
+        };
+    }
+    const parsed = parseTargetShorthand(action.target || action.action, action.kind, action.command);
+    return {
+        kind: parsed.kind,
+        command: parsed.command,
+        appRef: action.appRef || action.app || inherited.appRef,
+        datasetCode: action.datasetCode || inherited.datasetCode,
+        datatable: action.datatable || action.table || inherited.datatable,
+        sqlCode: action.sqlCode,
+        bffCode: action.bffCode,
+        bffId: action.bffId,
+        scriptName: action.scriptName,
+    };
+}
+function parseTargetShorthand(value, kind, command) {
+    if (typeof value === "string" && value.includes(".")) {
+        const [targetKind, targetCommand] = value.split(".", 2);
+        return {
+            kind: targetKind,
+            command: targetCommand,
+        };
+    }
+    return {
+        kind: kind || "data",
+        command: command || (typeof value === "string" ? value : "filter"),
+    };
+}
+function normalizeArgs(args) {
+    return (args || []).map((arg) => (typeof arg === "string" ? { name: arg, required: true } : { ...arg }));
+}
+function normalizeFlags(flags) {
+    if (!flags)
+        return [];
+    if (Array.isArray(flags)) {
+        return flags.map((flag) => ({
+            ...flag,
+            cliName: flag.cliName ? toKebabCase(flag.cliName) : toKebabCase(flag.name),
+        }));
+    }
+    return Object.entries(flags).map(([name, value]) => {
+        if (typeof value === "string") {
+            return {
+                name,
+                cliName: toKebabCase(name),
+                type: "string",
+                mapTo: value,
+            };
+        }
+        return {
+            name,
+            cliName: value.cliName ? toKebabCase(value.cliName) : toKebabCase(name),
+            type: value.type || "string",
+            description: value.description,
+            required: value.required,
+            default: value.default,
+            enum: value.enum,
+            mapTo: {
+                target: value.target || value.to || "",
+                operator: value.operator || value.op,
+                transform: value.transform,
+                omitEmpty: value.omitEmpty,
+            },
+        };
+    });
+}
+function normalizeMapInput(mapTo, args, flags) {
+    if (!mapTo || Array.isArray(mapTo))
+        return mapTo;
+    const argNames = new Set(args.map((arg) => arg.name));
+    const flagNames = new Set(flags.flatMap((flag) => [flag.name, flag.cliName]));
+    const normalized = {};
+    for (const [source, target] of Object.entries(mapTo)) {
+        normalized[normalizeMapSource(source, argNames, flagNames)] = target;
+    }
+    return normalized;
+}
+function normalizeMapSource(source, argNames, flagNames) {
+    if (source === "const"
+        || source.startsWith("flags.")
+        || source.startsWith("args.")
+        || source.startsWith("const.")
+        || source.startsWith("context.")
+        || source.startsWith("ctx.")) {
+        return source;
+    }
+    if (argNames.has(source))
+        return `args.${source}`;
+    if (flagNames.has(source))
+        return `flags.${source}`;
+    return `flags.${source}`;
+}
+function inferRisk(target) {
+    if (target.kind !== "data")
+        return "read";
+    if (target.command === "delete")
+        return "high-risk-write";
+    if (target.command === "create" || target.command === "batchCreate" || target.command === "update") {
+        return "write";
+    }
+    return "read";
 }

package/lib/service-tree/types.d.ts

@@ -14,11 +14,13 @@ export interface ServiceTreeAppBinding {
     appCode?: string;
     env?: string;
 }
+export type ServiceTreeAppBindingInput = string | ServiceTreeAppBinding;
 export interface ServiceTreeArg {
     name: string;
     description?: string;
     required?: boolean;
 }
+export type ServiceTreeArgInput = string | ServiceTreeArg;
 export interface ServiceTreeMapToRule {
     source?: string;
     target: string;
@@ -39,6 +41,21 @@ export interface ServiceTreeFlag {
     enum?: string[];
     mapTo?: string | Omit<ServiceTreeMapToRule, "source">;
 }
+export interface ServiceTreeSimpleFlag {
+    to?: string;
+    target?: string;
+    op?: string;
+    operator?: string;
+    type?: ServiceTreeValueType;
+    description?: string;
+    required?: boolean;
+    default?: unknown;
+    enum?: string[];
+    cliName?: string;
+    transform?: ServiceTreeMapTransform;
+    omitEmpty?: boolean;
+}
+export type ServiceTreeFlagsInput = ServiceTreeFlag[] | Record<string, string | ServiceTreeSimpleFlag>;
 export interface ServiceTreeTarget {
     kind: ServiceTreeTargetKind;
     command: ServiceTreeTargetCommand;
@@ -55,18 +72,62 @@ export interface ServiceTreeCommand {
     path: string | string[];
     description?: string;
     risk?: Risk;
-    args?: ServiceTreeArg[];
-    flags?: ServiceTreeFlag[];
+    args?: ServiceTreeArgInput[];
+    flags?: ServiceTreeFlagsInput;
     target: ServiceTreeTarget;
     params?: Record<string, unknown>;
+    defaults?: Record<string, unknown>;
+    map?: ServiceTreeMapTo;
+    mapTo?: ServiceTreeMapTo;
+}
+export interface ServiceTreeAction {
+    description?: string;
+    risk?: Risk;
+    action?: ServiceTreeTargetCommand | `${ServiceTreeTargetKind}.${ServiceTreeTargetCommand}`;
+    target?: ServiceTreeTarget | `${ServiceTreeTargetKind}.${ServiceTreeTargetCommand}`;
+    kind?: ServiceTreeTargetKind;
+    command?: ServiceTreeTargetCommand;
+    appRef?: string;
+    app?: string;
+    datasetCode?: string;
+    datatable?: string;
+    table?: string;
+    sqlCode?: string;
+    bffCode?: string;
+    bffId?: string | number;
+    scriptName?: string;
+    args?: ServiceTreeArgInput[];
+    flags?: ServiceTreeFlagsInput;
+    defaults?: Record<string, unknown>;
+    params?: Record<string, unknown>;
+    map?: ServiceTreeMapTo;
     mapTo?: ServiceTreeMapTo;
 }
+export interface ServiceTreeResource {
+    name?: string;
+    description?: string;
+    appRef?: string;
+    app?: string;
+    datasetCode?: string;
+    datatable?: string;
+    table?: string;
+    defaults?: Record<string, unknown>;
+    params?: Record<string, unknown>;
+    actions?: Record<string, ServiceTreeAction>;
+    resources?: Record<string, ServiceTreeResource>;
+}
 export interface ServiceTreeManifest {
     protocol?: string;
-    version: string;
-    service: ServiceTreeServiceInfo;
-    appBindings?: Record<string, ServiceTreeAppBinding>;
-    commands: ServiceTreeCommand[];
+    version?: string;
+    service: string | ServiceTreeServiceInfo;
+    name?: string;
+    description?: string;
+    app?: ServiceTreeAppBindingInput;
+    apps?: Record<string, ServiceTreeAppBindingInput>;
+    appBindings?: Record<string, ServiceTreeAppBindingInput>;
+    defaults?: Record<string, unknown>;
+    commands?: ServiceTreeCommand[];
+    resources?: Record<string, ServiceTreeResource>;
 }
 export interface NormalizedServiceTreeFlag extends ServiceTreeFlag {
     cliName: string;

package/lib/service-tree/validate.js

@@ -1,4 +1,5 @@
-import { isCommandSegment, isDatatableName, isDatasetCode, isServiceCode, splitServiceTreePath, toKebabCase, } from "./path.js";
+import { isCommandSegment, isDatatableName, isDatasetCode, isServiceCode, } from "./path.js";
+import { normalizeServiceTreeManifest } from "./normalize.js";
 const DATA_COMMANDS = new Set(["filter", "getOne", "aggregate", "create", "batchCreate", "update", "delete"]);
 const SQL_COMMANDS = new Set(["exec"]);
 const BFF_COMMANDS = new Set(["exec"]);
@@ -9,35 +10,54 @@ export function validateServiceTreeManifest(manifest) {
         push(issues, "error", "$", "Manifest must be a JSON object.");
         return buildReport(issues);
     }
-    if (typeof manifest.version !== "string" || !manifest.version.trim()) {
-        push(issues, "error", "$.version", "version is required.");
+    if (typeof manifest.service === "string") {
+        if (!isServiceCode(manifest.service)) {
+            push(issues, "error", "$.service", "service must be lower kebab-case.");
+        }
     }
-    if (!isRecord(manifest.service)) {
+    else if (!isRecord(manifest.service)) {
         push(issues, "error", "$.service", "service is required.");
     }
     else if (typeof manifest.service.code !== "string" || !isServiceCode(manifest.service.code)) {
         push(issues, "error", "$.service.code", "service.code must be lower kebab-case.");
     }
-    if (!Array.isArray(manifest.commands) || manifest.commands.length === 0) {
-        push(issues, "error", "$.commands", "commands must be a non-empty array.");
+    let hasShapeError = false;
+    if (manifest.commands !== undefined && !Array.isArray(manifest.commands)) {
+        push(issues, "error", "$.commands", "commands must be an array.");
+        hasShapeError = true;
+    }
+    if (manifest.resources !== undefined && !isRecord(manifest.resources)) {
+        push(issues, "error", "$.resources", "resources must be an object.");
+        hasShapeError = true;
+    }
+    if (hasShapeError) {
+        return buildReport(issues);
+    }
+    if (!Array.isArray(manifest.commands) && !isRecord(manifest.resources)) {
+        push(issues, "error", "$", "commands or resources is required.");
+        return buildReport(issues);
+    }
+    let normalized;
+    try {
+        normalized = normalizeServiceTreeManifest(manifest);
+    }
+    catch (error) {
+        push(issues, "error", "$", error instanceof Error ? error.message : String(error));
+        return buildReport(issues);
+    }
+    if (normalized.commands.length === 0) {
+        push(issues, "error", "$", "Service tree must define at least one command.");
         return buildReport(issues);
     }
-    const serviceCode = isRecord(manifest.service) && typeof manifest.service.code === "string"
-        ? manifest.service.code
-        : "";
     const seenPaths = new Set();
-    manifest.commands.forEach((command, index) => {
-        validateCommand(command, index, serviceCode, seenPaths, issues);
+    normalized.commands.forEach((command, index) => {
+        validateCommand(command, index, seenPaths, issues);
     });
     return buildReport(issues);
 }
-function validateCommand(command, index, serviceCode, seenPaths, issues) {
+function validateCommand(command, index, seenPaths, issues) {
     const base = `$.commands[${index}]`;
-    if (!isRecord(command)) {
-        push(issues, "error", base, "Command must be an object.");
-        return;
-    }
-    const path = splitServiceTreePath(command.path || []);
+    const path = command.path;
     if (path.length === 0) {
         push(issues, "error", `${base}.path`, "path is required.");
     }
@@ -46,8 +66,7 @@ function validateCommand(command, index, serviceCode, seenPaths, issues) {
             push(issues, "error", `${base}.path[${partIndex}]`, "Command path segments must be lower kebab-case.");
         }
     }
-    const fullPath = path[0] === serviceCode ? path : [serviceCode, ...path];
-    const fullKey = fullPath.join(" ");
+    const fullKey = command.fullPath.join(" ");
     if (seenPaths.has(fullKey)) {
         push(issues, "error", `${base}.path`, `Duplicate command path: ${fullKey}.`);
     }
@@ -105,6 +124,7 @@ function validateFlags(flags, path, issues) {
         return;
     }
     const seen = new Set();
+    const seenCliNames = new Set();
     flags.forEach((flag, index) => {
         const flagPath = `${path}[${index}]`;
         if (!isRecord(flag)) {
@@ -119,9 +139,11 @@ function validateFlags(flags, path, issues) {
             push(issues, "error", `${flagPath}.name`, `Duplicate flag name: ${flag.name}.`);
         }
         seen.add(flag.name);
-        const cliName = typeof flag.cliName === "string" ? flag.cliName : toKebabCase(flag.name);
-        if (cliName !== toKebabCase(cliName)) {
-            push(issues, "error", `${flagPath}.cliName`, "flag.cliName must be kebab-case.");
+        if (typeof flag.cliName === "string") {
+            if (seenCliNames.has(flag.cliName)) {
+                push(issues, "error", `${flagPath}.cliName`, `Duplicate CLI flag name: ${flag.cliName}.`);
+            }
+            seenCliNames.add(flag.cliName);
         }
         if (typeof flag.type !== "string" || !VALUE_TYPES.has(flag.type)) {
             push(issues, "error", `${flagPath}.type`, "flag.type must be string, number, boolean, or json.");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lovrabet/cli-framework",
-  "version": "1.0.4-beta.2",
+  "version": "1.0.4",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",