feat: xanoscript to be included in generate-repo command (#152)

Author: MihalyToth20

.changeset/brave-suits-punch.md

@@ -0,0 +1,6 @@
+---
+"@calycode/core": minor
+"@calycode/cli": minor
+---
+
+feat: include mcp_server, addon, agent, middleware in the workspace xs export

.changeset/young-clowns-push.md

@@ -0,0 +1,8 @@
+---
+'@calycode/core': minor
+'@calycode/cli': minor
+---
+
+chore: add query VERBS into xanoscript generation, to avoid overrides
+chore: cleanup of repo directory structure generation, added notes to the function
+feat: integrating xanoscript into repo-generation

.continue/rules/review.md

@@ -0,0 +1,19 @@
+---
+invokable: true
+---
+
+Review this code for potential issues, including:
+
+- Correct Xano CLI command registration (commands are discoverable, correctly registered, and context is managed)
+- Monorepo structure consistency (all packages properly separated, with clear interfaces and responsibilities)
+- Adherence to TypeScript best practices, type safety, and explicit type usage
+- Efficient and reliable automation in code generation, documentation, OAS, registry, backup, and testing workflows
+- Clear separation between CLI, business logic (core), types, and utility functions
+- Valid, up-to-date configuration, schema, and CI/CD scripts
+- Readable, maintainable, and well-commented code (especially around CLI entrypoints and registry features)
+- Secure handling of credentials, tokens, and configuration (especially when running local/GitHub Actions)
+- Actions and scripts should not break if Xano metadata/API structure changes subtly
+- Registry and codegen should be robust for large projects and handle edge cases (naming, conflicts, missing metadata)
+- Documentation and CLI output should be clear and actionable for humans
+
+Provide specific, actionable feedback for improvements.

AGENTS.md

@@ -0,0 +1,56 @@
+# Repository Overview
+
+## Project Description
+This project provides a suite of tools to improve developer experience with Xano, focusing on clarity, transparency, automation, and robust version control for Xano backend developments. The main goal is to minimize reliance on AI by offering reliable CLI-based workflows for code generation, documentation, testing, and registry management. The tools allow teams to automate backups, generate OpenAPI specifications, create fully browsable repositories from Xano metadata, scaffold and serve reusable component registries, and run automated tests—all integrated with Git workflows and CI/CD.
+
+**Key technologies used:**
+- Node.js (>=18)
+- TypeScript
+- PNPM workspaces
+- TurboRepo for monorepo builds
+- Jest for testing
+- Esbuild/Rollup for bundling
+- Commander.js for the CLI
+- js-yaml for YAML processing
+
+## Architecture Overview
+- **Monorepo Layout:** Managed by PNPM and TurboRepo with logical separation by package:
+    - `@calycode/cli`: The main CLI.
+    - `@calycode/core`: Business and program logic for processing Xano data and interfacing with metadata APIs.
+    - `@calycode/types`: Shared type definitions.
+    - `@calycode/utils`: Shared utilities.
+- **CLI Entry Point:** The CLI (`xano`) registers commands for setup, codegen, OAS gen, tests, registry, backup, etc. Each command routes into core business logic via composed packages.
+- **Extensible Registry System:** For sharing and consuming standardized Xano components (functions, tables, queries, etc.).
+- **Configurable Storage and Context Management:** Multi-user, multi-environment ready.
+- **Automated CI/CD Ready:** Designed to run in GitHub Actions or local workflows.
+
+**Data Flow & Interactions:**
+- User issues a CLI command (`xano ...`)
+- CLI parses config/context, invokes logic in `@calycode/core`
+- Utilities help fetch, transform, and validate data
+- Output is written to file system, appropriate directories, or remote registries
+- CI/CD scripts automate build and publish steps
+
+## Directory Structure
+- **./packages**: Main monorepo packages (cli, core, types, utils)
+- **./docs**: Documentation, including CLI command references
+- **./schemas**: JSON schemas for registries and related features
+- **.github/**: GitHub workflows for CI/CD and publishing
+- **scripts/**: Build, clean, and documentation generation scripts
+- **test-config.json, turbo.json, pnpm-workspace.yaml**: Config files for monorepo tooling
+- **Entry Points:**
+   - CLI: `packages/cli/src/index.ts` and `dist/index.cjs`
+   - Core logic: `packages/core/src/index.ts`
+
+## Development Workflow
+- **Install/Setup**: `pnpm install` to install everything. (Requires pnpm)
+- **Build**: `pnpm build` (runs TurboRepo, builds all packages)
+- **Run CLI**: `pnpm xano <command>` or if globally linked, `xano <command>`
+- **Testing**: `pnpm test` (runs tests across all packages)
+- **Linting/Formatting**: Eslint/Prettier with default configs, e.g. `pnpm lint`, some packages have their own config and scripts
+- **CI/CD**: See `.github/workflows`. Ready for automated release, docs update, and registry actions
+
+---
+
+- See also `docs/README.md` and `docs/commands` for command reference.
+- Key configuration in `.changeset/`, `schemas/registry/`, and package-level config files.

packages/core/src/features/process-xano/core/generateRunReadme.ts

@@ -31,7 +31,7 @@ function getDboLink(method, dboMapping) {
    const dboId = method.context?.dbo?.id;
    if (dboId && dboMapping[dboId]) {
       const dboName = dboMapping[dboId].name;
-      const dboPath = `/src/dbo/${dboName.replace(/\//g, '_')}/`;
+      const dboPath = `/src/table/${dboName.replace(/\//g, '_')}/`;
       return `**[${dboName}](${dboPath})**`;
    }
    return '';

packages/core/src/features/process-xano/core/processItem.ts

@@ -2,24 +2,53 @@ import { generateQueryLogicDescription } from './generateRunReadme';
 import { convertXanoDBDescription } from '../adapters/dbmlGenerator';
 import { sanitizeFileName, joinPath } from '@repo/utils';
 
-function getItemDir({ key, item, dirPath, appMapping }) {
-   let baseDir;
-   let itemName = item.name || 'unnamed';
-
-   if (key === 'query' && item.app?.id) {
-      const appName = appMapping[item.app.id] || `app_${item.app.id}`;
-      baseDir = joinPath('app', appName, sanitizeFileName(itemName));
-   } else if (key === 'app') {
-      baseDir = joinPath(dirPath, itemName);
-   } else {
-      baseDir = joinPath(dirPath, sanitizeFileName(itemName));
-   }
-
-   // Queries may have a verb subfolder
-   if (key === 'query' && item.verb) {
-      baseDir = joinPath(baseDir, item.verb);
+/**
+ * Determines the target directory path for a given schema item, normalizing names for human-friendly structure.
+ * Handles special cases for item types (e.g., 'dbo', 'query', 'trigger') and integrates API group mappings.
+ *
+ * @param {string} key - The schema item type (e.g., 'dbo', 'query', 'app', 'trigger').
+ * @param {Object} item - The schema item object, with metadata and Xano schema.
+ * @param {string} dirPath - The base directory path for output.
+ * @param {Object} appMapping - Maps app IDs to human-friendly names.
+ * @returns {string} The computed directory path for the item.
+ */
+function getItemDir({
+   key,
+   item,
+   dirPath,
+   appMapping,
+}: {
+   key: string;
+   item: any;
+   dirPath: string;
+   appMapping: Record<string, string>;
+}): string {
+   // Get a safe, human-friendly item name
+   const itemName = sanitizeFileName(item.name ?? 'unnamed');
+
+   // Compute the base directory depending on the item type
+   switch (key) {
+      case 'query': {
+         // Use mapped app name if available
+         const appId = item.app?.id;
+         const appName = appId ? sanitizeFileName(appMapping[appId] ?? `app_${appId}`) : undefined;
+         let baseDir = appId ? joinPath('app', appName, itemName) : joinPath(dirPath, itemName);
+         // Add verb subfolder if present
+         if (item.verb) baseDir = joinPath(baseDir, item.verb);
+         return baseDir;
+      }
+      case 'app':
+         return joinPath(dirPath, itemName);
+      case 'dbo':
+         return joinPath('table', itemName);
+      case 'trigger':
+         if (item.obj_type === 'database') {
+            return joinPath('table', key, itemName);
+         }
+         return joinPath(dirPath, itemName);
+      default:
+         return joinPath(dirPath, itemName);
    }
-   return baseDir;
 }
 
 function makeReadmeContent({ key, item, functionMapping, dboMapping }) {

packages/core/src/features/process-xano/index.ts

@@ -28,12 +28,12 @@ async function rebuildDirectoryStructure({
    workspace?: string;
    branch?: string;
 }) {
-   const { dbo, app, query, function: func, addon, trigger, task, middleware } = jsonData.payload;
+   const { addon, app, dbo, function: func, middleware, query, task, trigger } = jsonData.payload;
 
    core.emit('start', { name: 'generate-repo', payload: null });
 
    // Mappings
-   const appMapping = buildMapping(app, (a) => a.name.replace(/\//g, '_'));
+   const appMapping = buildMapping(app, (a) => sanitizeFileName(a.name));
    const appDescriptions = buildMapping(app, (a) => a.description || '//...');
    const functionMapping = buildMapping(func, (f) => ({
       name: f.name,
@@ -42,7 +42,7 @@ async function rebuildDirectoryStructure({
    }));
    const dboMapping = buildMapping(dbo, (d) => ({
       name: d.name,
-      path: `dbo/${sanitizeFileName(d.name)}`,
+      path: `table/${sanitizeFileName(d.name)}`,
       description: d.description ?? '',
    }));
    const appQueries = {};

packages/core/src/implementations/build-xanoscript-repo.ts

@@ -2,6 +2,25 @@ import { metaApiGet, sanitizeFileName } from '@repo/utils';
 import type { Caly } from '..';
 import type { CoreContext } from '@repo/types';
 
+const SUPPORTED_ENTITIES = [
+   'addon',
+   'agent',
+   'agent/trigger',
+   'apigroup',
+   'function',
+   'mcp_server',
+   'mcp_server/trigger',
+   'middleware',
+   'realtime/channel',
+   'realtime/channel/trigger',
+   'table',
+   'table/trigger',
+   'task',
+   'tool',
+   'trigger',
+   'workflow_test',
+];
+
 async function fetchAndProcessEntities({
    baseUrl,
    token,
@@ -36,9 +55,11 @@ async function fetchAndProcessEntities({
       const sanitizedName = sanitizeFileName(name);
       const path =
          entity === 'api'
-            ? sanitizedName
+            ? `${sanitizedName}/${item.verb.toUpperCase()}`
             : entity === 'table'
-            ? `dbo/${sanitizedName}`
+            ? `table/${sanitizedName}`
+            : entity === 'apigroup'
+            ? `app/${sanitizedName}`
             : `${entity}/${sanitizedName}`;
       const metaDataContent = item;
       delete metaDataContent.xanoscript;
@@ -89,13 +110,13 @@ async function buildXanoscriptRepoImplementation({
    const branchLabel = branchConfig.label;
    // Supported entities: functions, tables, api groups > apis
    // [ ] Add hidden pagination to make sure that all functions and queries are captured.
-   for (const entity of ['function', 'table']) {
+   for (const entity of SUPPORTED_ENTITIES) {
       core.emit('progress', {
          name: 'xs-repo-generation',
          payload: {
             entity,
          },
-         percent: ((['function', 'table'].indexOf(entity) + 1) / 3) * 60,
+         percent: ((SUPPORTED_ENTITIES.indexOf(entity) + 1) / 3) * 60,
       });
       const tempResults = await fetchAndProcessEntities({
          baseUrl,
@@ -111,7 +132,7 @@ async function buildXanoscriptRepoImplementation({
          payload: {
             entity,
          },
-         percent: ((['function', 'table'].indexOf(entity) + 1) / 2) * 60,
+         percent: ((SUPPORTED_ENTITIES.indexOf(entity) + 1) / 2) * 60,
       });
    }
 
@@ -158,7 +179,7 @@ async function buildXanoscriptRepoImplementation({
 
       results.push(
          ...tempResults.map((item) => ({
-            // ADd the apigroup name to the path for nice folder structure
+            // Add the apigroup name to the path for nice folder structure
             path: `app/${apiGroupPath}/${item.path}`,
             content: item.content,
          }))
@@ -176,4 +197,3 @@ async function buildXanoscriptRepoImplementation({
 }
 
 export { buildXanoscriptRepoImplementation };
-