feat: including xanoscript into the repo generation, minor docs updates (#145)

MihalyToth20 · web-flow · commit b0d18f7b26dc · 2025-10-22T21:54:04.000+02:00
diff --git a/.changeset/calm-sheep-rest.md b/.changeset/calm-sheep-rest.md
@@ -0,0 +1,6 @@
+---
+"@calycode/core": patch
+"@calycode/cli": patch
+---
+
+chore: updating and expanding on the documentation of each command
diff --git a/.changeset/fuzzy-bushes-battle.md b/.changeset/fuzzy-bushes-battle.md
@@ -0,0 +1,6 @@
+---
+"@calycode/core": patch
+"@calycode/cli": patch
+---
+
+feat: including xanoscript in the main repository generation (tables, functions, apis)
diff --git a/packages/cli/src/commands/backups.ts b/packages/cli/src/commands/backups.ts
@@ -150,12 +150,12 @@ function registerExportBackupCommand(program, core) {
 function registerRestoreBackupCommand(program, core) {
    const cmd = program
       .command('restore-backup')
-      .description('Restore a backup to a Xano Workspace via Metadata API');
+      .description('Restore a backup to a Xano Workspace via Metadata API. DANGER! This action will override all business logic and restore the original v1 branch. Data will be also restored from the backup file.');
 
    addPartialContextOptions(cmd);
 
-   cmd.option('--source-backup <file>', 'Path to the backup file to restore')
-      .option('--force', 'Force restoration without confirmation')
+   cmd.option('-S, --source-backup <file>', 'Local path to the backup file to restore.')
+      .option('--force', 'Force restoration without confirmation, not advised to be specified, useful when ran from a CI/CD pipeline and consequences are acknowledged.')
       .action(
          withErrorHandler(async (options) => {
             await restorationWizard({
diff --git a/packages/cli/src/commands/generate-code.ts b/packages/cli/src/commands/generate-code.ts
@@ -12,7 +12,6 @@ import {
 } from '../utils/index';
 import { runOpenApiGenerator } from '../features/code-gen/open-api-generator';
 
-// [ ] CLI only feature
 async function generateCodeFromOas({
    instance,
    workspace,
@@ -131,7 +130,7 @@ function registerGenerateCodeCommand(program, core) {
    )
       .option(
          '--args <args>',
-         'Additional arguments to pass to the generator. See https://openapi-generator.tech/docs/usage#generate'
+         'Additional arguments to pass to the generator. For options for each generator see https://openapi-generator.tech/docs/usage#generate'
       )
       .option(
          '--debug',
diff --git a/packages/cli/src/commands/generate-oas.ts b/packages/cli/src/commands/generate-oas.ts
@@ -69,7 +69,6 @@ async function updateOasWizard({
    for (const { group, generatedItems } of allGroupResults) {
       const apiGroupNameNorm = normalizeApiGroupName(group);
 
-      // [x] This is going to be relative to the working dir, but we have to force the structure...
       const outputPath = replacePlaceholders(instanceConfig.openApiSpec.output, {
          '@': await findProjectRoot(),
          instance: instanceConfig.name,
@@ -96,7 +95,7 @@ async function updateOasWizard({
 function registerGenerateOasCommand(program, core) {
    const cmd = program
       .command('generate-oas')
-      .description('Update and generate OpenAPI spec(s) for the current context.');
+      .description('Update and generate OpenAPI spec(s) for the current context, or all API groups simultaneously. This generates an opinionated API documentation powered by Scalar API Reference. + this command brings the Swagger docs to OAS 3.1+ version.');
 
    addFullContextOptions(cmd);
    addApiGroupOptions(cmd);
diff --git a/packages/cli/src/commands/generate-repo.ts b/packages/cli/src/commands/generate-repo.ts
@@ -100,7 +100,12 @@ async function generateRepo({
    const fileContents = await core.storage.readFile(inputFile, 'utf8');
    const jsonData = load(fileContents);
 
-   const plannedWrites: { path: string; content: string }[] = await core.generateRepo(jsonData);
+   const plannedWrites: { path: string; content: string }[] = await core.generateRepo({
+      jsonData,
+      instance: instanceConfig.name,
+      workspace: workspaceConfig.name,
+      branch: branchConfig.label,
+   });
    log.step(`Writing Repository to the output directory -> ${outputDir}`);
    await Promise.all(
       plannedWrites.map(async ({ path, content }) => {
@@ -120,14 +125,14 @@ async function generateRepo({
 function registerGenerateRepoCommand(program, core) {
    const cmd = program
       .command('generate-repo')
-      .description('Process Xano workspace into repo structure')
-      .option('--input <file>', 'workspace yaml file')
-      .option('--output <dir>', 'output directory (overrides config)');
+      .description('Process Xano workspace into repo structure. We use the export-schema metadata API to offer the full details. However that is enriched with the Xanoscripts after Xano 2.0 release.')
+      .option('-I, --input <file>', 'Workspace yaml file from a local source, if present.')
+      .option('-O, --output <dir>', 'Output directory (overrides default config), useful when ran from a CI/CD pipeline and want to ensure consistent output location.');
 
    addFullContextOptions(cmd);
    addPrintOutputFlag(cmd);
 
-   cmd.option('--fetch', 'Specify this if you want to fetch the workspace schema from Xano').action(
+   cmd.option('-F, --fetch', 'Forces fetching the workspace schema from the Xano instance via metadata API.').action(
       withErrorHandler(async (opts) => {
          await generateRepo({
             instance: opts.instance,
diff --git a/packages/cli/src/commands/generate-xanoscript-repo.ts b/packages/cli/src/commands/generate-xanoscript-repo.ts
@@ -82,7 +82,7 @@ async function generateXanoscriptRepo({ instance, workspace, branch, core, print
 function registerBuildXanoscriptRepoCommand(program, core) {
    const cmd = program
       .command('generate-xs-repo')
-      .description('Process Xano workspace into repo structure');
+      .description('Process Xano workspace into repo structure. Supports table, function and apis as of know. Xano VSCode extension is the preferred solution over this command. Outputs of this process are also included in the default repo generation command.');
 
    addFullContextOptions(cmd);
    addPrintOutputFlag(cmd);
diff --git a/packages/cli/src/commands/registry.ts b/packages/cli/src/commands/registry.ts
@@ -127,7 +127,9 @@ async function installComponentToXano(file, resolvedContext, core) {
 function registerRegistryAddCommand(program, core) {
    const cmd = program
       .command('registry-add')
-      .description('Add a prebuilt component to the current Xano context.');
+      .description(
+         'Add a prebuilt component to the current Xano context, essentially by pushing an item from the registry to the Xano instance.'
+      );
 
    addFullContextOptions(cmd);
    cmd.option('--components', 'Comma-separated list of components to add')
@@ -160,7 +162,7 @@ function registerRegistryScaffoldCommand(program, core) {
       .description(
          'Scaffold a Xano registry folder with a sample component. Xano registry can be used to share and reuse prebuilt components. In the registry you have to follow the [registry](https://calycode.com/schemas/registry/registry.json) and [registry item](https://calycode.com/schemas/registry/registry-item.json) schemas.'
       )
-      .option('--output <path>', 'Output path for the registry')
+      .option('--output <path>', 'Local output path for the registry')
       .option(
          '--instance <instance>',
          'The instance name. This is used to fetch the instance configuration. The value provided at the setup command.'
diff --git a/packages/cli/src/commands/run-tests.ts b/packages/cli/src/commands/run-tests.ts
@@ -128,17 +128,18 @@ ${'-'.repeat(60)}`
    );
 }
 
-// [ ] CLI
 function registerRunTestCommand(program, core) {
    const cmd = program
       .command('run-test')
-      .description('Run an API test suite via the OpenAPI spec. WIP...');
+      .description(
+         'Run an API test suite via the OpenAPI spec. To execute this command a specification is required. Find the schema here: https://calycode.com/schemas/testing/config.json '
+      );
 
    addFullContextOptions(cmd);
    addApiGroupOptions(cmd);
    addPrintOutputFlag(cmd);
 
-   cmd.option('--test-config-path <path>', 'Path to a test configuration file.').action(
+   cmd.option('--test-config-path <path>', 'Local path to the test configuration file.').action(
       withErrorHandler(async (options) => {
          await runTest({
             ...options,
diff --git a/packages/cli/src/commands/serve.ts b/packages/cli/src/commands/serve.ts
@@ -84,9 +84,9 @@ function registerRegistryServeCommand(program) {
    program
       .command('serve-registry')
       .description(
-         'Serve the registry locally. This allows you to actually use your registry without deploying it.'
+         'Serve the registry locally. This allows you to actually use your registry without deploying it to any remote host.'
       )
-      .option('--root <path>', 'Where did you put your registry?')
+      .option('--root <path>', 'Where did you put your registry? (Local path to the registry directory)')
       .option(
          '--listen <port>',
          'The port where you want your registry to be served locally. By default it is 5000.'
@@ -104,7 +104,7 @@ function registerRegistryServeCommand(program) {
 function registerOasServeCommand(program, core) {
    const cmd = program
       .command('serve-oas')
-      .description('Serve the Open API specification locally for quick visual check.');
+      .description('Serve the Open API specification locally for quick visual check, or to test your APIs via the Scalar API reference.');
    addFullContextOptions(cmd);
    addApiGroupOptions(cmd);
    cmd.option(
diff --git a/packages/cli/src/commands/setup-instance.ts b/packages/cli/src/commands/setup-instance.ts
@@ -8,17 +8,21 @@ async function setupInstanceWizard(core) {
    // Gather info from user
    let nameInput = (
       (await text({
-         message: 'Name this Xano instance (e.g. prod, staging, client-a):',
+         message:
+            'Give an easy to remember name to this Xano instance (e.g. prod, staging, client-a), you will use this to identify it during command usage:',
       })) as string
    ).trim();
    const instanceName = sanitizeInstanceName(nameInput);
    const url = (
-      (await text({ message: `What's the base URL for "${instanceName}"?` })) as string
+      (await text({
+         message: `What's the base URL for "${instanceName}"? This is your instance URL.`,
+      })) as string
    ).trim();
    const apiKey = await password({ message: `Enter the Metadata API key for "${instanceName}":` });
    const defaultPath = `xano/${instanceName}`;
    let userDirectory = (await text({
-      message: 'Where do you want the repo to be initialized at?',
+      message:
+         'Where do you want the repo to be initialized at? (What is the local folder where we will set up your project)',
       placeholder: defaultPath,
    })) as string;
    if (userDirectory) {
@@ -52,7 +56,6 @@ Here’s exactly what we track:
    • Technical data:
       – IP address (IPv6)
       – Timestamp
-      – PostHog library version
 
 By continuing to use @calycode/cli, you consent to this data collection.
 We appreciate your support and commitment to making @calycode/cli better!
@@ -72,11 +75,16 @@ We appreciate your support and commitment to making @calycode/cli better!
 export function registerSetupCommand(program, core) {
    program
       .command('setup')
-      .description('Setup Xano instance configurations (interactively or via flags)')
+      .description(
+         'Setup Xano instance configurations (interactively or via flags), this enables the CLI to know about context, APIs and in general this is required for any command to succeed.'
+      )
       .option('--name <name>', 'Instance name (for non-interactive setup)')
       .option('--url <url>', 'Instance base URL (for non-interactive setup)')
       .option('--token <token>', 'Metadata API token (for non-interactive setup)')
-      .option('--no-set-current', 'Do not set this instance as the current context')
+      .option(
+         '--no-set-current',
+         'Flag to not set this instance as the current context, by default it is set.'
+      )
       .action(
          withErrorHandler(async (opts) => {
             ensureGitignore();
@@ -89,7 +97,6 @@ export function registerSetupCommand(program, core) {
                   setAsCurrent: opts.setCurrent,
                });
             } else {
-               // Interactive wizard for local development
                await setupInstanceWizard(core);
             }
          })
diff --git a/packages/core/src/features/process-xano/index.ts b/packages/core/src/features/process-xano/index.ts
@@ -2,6 +2,7 @@ import { processItem } from './core/processItem';
 import { sanitizeFileName } from '@repo/utils';
 import { generateStructureDiagrams } from './core/generate-structure-diagrams';
 import type { Caly } from '../../';
+import { buildXanoscriptRepoImplementation } from '../../implementations/build-xanoscript-repo';
 
 const buildMapping = (entities, keyBuilder) =>
    Array.isArray(entities)
@@ -12,7 +13,21 @@ const buildMapping = (entities, keyBuilder) =>
         }, {})
       : {};
 
-async function rebuildDirectoryStructure(jsonData, core: Caly) {
+async function rebuildDirectoryStructure({
+   jsonData,
+   storage,
+   core,
+   instance,
+   workspace,
+   branch,
+}: {
+   jsonData: any;
+   storage: any;
+   core: Caly;
+   instance?: string;
+   workspace?: string;
+   branch?: string;
+}) {
    const { dbo, app, query, function: func, addon, trigger, task, middleware } = jsonData.payload;
 
    core.emit('start', { name: 'generate-repo', payload: null });
@@ -69,7 +84,14 @@ async function rebuildDirectoryStructure(jsonData, core: Caly) {
 
    core.emit('end', { name: 'generate-repo', payload: null });
 
+   const xanoScriptRepoOutput = await buildXanoscriptRepoImplementation({
+      storage: storage,
+      core: core,
+      options: { instance, workspace, branch },
+   });
+
    return [
+      ...(xanoScriptRepoOutput ?? []),
       ...stagedProcessOutput,
       ...generateStructureDiagrams(appQueries, appMapping, appDescriptions),
    ];
diff --git a/packages/core/src/implementations/build-xanoscript-repo.ts b/packages/core/src/implementations/build-xanoscript-repo.ts
@@ -34,7 +34,12 @@ async function fetchAndProcessEntities({
    for (const item of allItems) {
       const { name, xanoscript } = item;
       const sanitizedName = sanitizeFileName(name);
-      const path = entity === 'api' ? sanitizedName : `${entity}/${sanitizedName}`;
+      const path =
+         entity === 'api'
+            ? sanitizedName
+            : entity === 'table'
+            ? `dbo/${sanitizedName}`
+            : `${entity}/${sanitizedName}`;
       const metaDataContent = item;
       delete metaDataContent.xanoscript;
       tempResults.push({
@@ -121,6 +126,7 @@ async function buildXanoscriptRepoImplementation({
          per_page: 500,
          sort: 'name',
          order: 'asc',
+         include_xanoscript: true,
       },
    });
    const apiGroups = apiGroupsResponse.items ?? [];
@@ -153,7 +159,7 @@ async function buildXanoscriptRepoImplementation({
       results.push(
          ...tempResults.map((item) => ({
             // ADd the apigroup name to the path for nice folder structure
-            path: `${apiGroupPath}/${item.path}`,
+            path: `app/${apiGroupPath}/${item.path}`,
             content: item.content,
          }))
       );
@@ -171,4 +177,3 @@ async function buildXanoscriptRepoImplementation({
 
 export { buildXanoscriptRepoImplementation };
 
-//
diff --git a/packages/core/src/implementations/generate-repo.ts b/packages/core/src/implementations/generate-repo.ts
@@ -1,8 +1,29 @@
 import type { Caly } from '..';
 import { rebuildDirectoryStructure } from '../features/process-xano';
 
-async function generateRepoImplementation(jsonData: any, core: Caly): Promise<{ path: string; content: string }[]> {
-   return await rebuildDirectoryStructure(jsonData, core);
+async function generateRepoImplementation({
+   jsonData,
+   storage,
+   core,
+   instance,
+   workspace,
+   branch,
+}: {
+   jsonData: any;
+   storage: any;
+   core: Caly;
+   instance?: string;
+   workspace?: string;
+   branch?: string;
+}): Promise<{ path: string; content: string }[]> {
+   return await rebuildDirectoryStructure({
+      jsonData,
+      storage,
+      core,
+      instance,
+      workspace,
+      branch,
+   });
 }
 
 export { generateRepoImplementation };
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
@@ -208,8 +208,26 @@ export class Caly extends TypedEmitter<EventMap> {
     * }
     * ```
     */
-   async generateRepo(jsonData: any): Promise<{ path: string; content: string }[]> {
-      const response = await generateRepoImplementation(jsonData, this);
+   async generateRepo({
+      jsonData,
+      instance,
+      workspace,
+      branch,
+   }: {
+      jsonData: any;
+      instance?: string;
+      workspace?: string;
+      branch?: string;
+   }): Promise<{ path: string; content: string }[]> {
+      const response = await generateRepoImplementation({
+         jsonData,
+         storage: this.storage,
+         core: this,
+         instance,
+         workspace,
+         branch,
+      });
+
       return response;
    }
 
