From 91d81cf7f9f01fb81b57d4d9e208525b0df763dd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mih=C3=A1ly=20T=C3=B3th?= Date: Fri, 10 Apr 2026 09:14:24 +0200 Subject: [PATCH 1/5] refactor!: migrate CLI command from xano to caly-xano Rename the published binary and help output to avoid conflicts with Xano's official CLI, and provide explicit legacy guidance for old invocations. Update docs/installers/guides plus a changeset so users can migrate scripts and CI safely. --- .changeset/rapid-lions-jump.md | 5 + README.md | 10 +- docs/README.md | 10 +- docs/_sidebar.md | 11 +- docs/commands/backup-export.md | 8 +- docs/commands/backup-restore.md | 8 +- docs/commands/backup.md | 8 +- docs/commands/context-show.md | 8 +- docs/commands/context.md | 8 +- docs/commands/generate-codegen.md | 8 +- docs/commands/generate-docs.md | 8 +- docs/commands/generate-repo.md | 8 +- docs/commands/generate-spec.md | 8 +- docs/commands/generate-xanoscript.md | 8 +- docs/commands/generate.md | 8 +- docs/commands/init.md | 8 +- docs/commands/oc-init.md | 8 +- docs/commands/oc-native-host.md | 8 +- docs/commands/oc-run.md | 8 +- docs/commands/oc-serve.md | 8 +- docs/commands/oc-skills-clear-cache.md | 21 + docs/commands/oc-skills-install.md | 26 ++ docs/commands/oc-skills-status.md | 21 + docs/commands/oc-skills-update.md | 21 + docs/commands/oc-skills.md | 28 ++ docs/commands/oc-templates-clear-cache.md | 8 +- docs/commands/oc-templates-install.md | 8 +- docs/commands/oc-templates-status.md | 8 +- docs/commands/oc-templates-update.md | 8 +- docs/commands/oc-templates.md | 8 +- docs/commands/oc.md | 9 +- docs/commands/registry-add.md | 8 +- docs/commands/registry-scaffold.md | 8 +- docs/commands/registry.md | 8 +- docs/commands/serve-registry.md | 8 +- docs/commands/serve-spec.md | 8 +- docs/commands/serve.md | 8 +- docs/commands/test-run.md | 8 +- docs/commands/test.md | 8 +- docs/guides/git-workflow.md | 92 ++-- docs/guides/opencode-setup.md | 429 ++++++++++++++++++ docs/guides/patterns.md | 26 +- docs/guides/registry-authoring.md | 22 +- docs/guides/scaffolding.md | 22 +- docs/guides/testing.md | 50 +- docs/guides/xanoscript.md | 18 +- docs/xano.md | 9 +- package.json | 5 +- packages/cli/README.md | 26 +- packages/cli/package.json | 6 +- packages/cli/scripts/README.md | 4 +- packages/cli/scripts/dev/install-unix.sh | 10 +- packages/cli/scripts/dev/install-win.bat | 10 +- packages/cli/scripts/installer/install.ps1 | 22 +- packages/cli/scripts/installer/install.sh | 22 +- packages/cli/src/commands/opencode/index.ts | 8 +- packages/cli/src/index-bundled.ts | 2 + packages/cli/src/index.ts | 2 + packages/cli/src/program.ts | 2 +- .../src/utils/commands/main-program-utils.ts | 14 +- .../cli/src/utils/legacy-command-guard.ts | 25 + scripts/generate-caly-cli-docs.ts | 6 +- scripts/legacy-xano-command.mjs | 4 + 63 files changed, 915 insertions(+), 315 deletions(-) create mode 100644 .changeset/rapid-lions-jump.md create mode 100644 docs/commands/oc-skills-clear-cache.md create mode 100644 docs/commands/oc-skills-install.md create mode 100644 docs/commands/oc-skills-status.md create mode 100644 docs/commands/oc-skills-update.md create mode 100644 docs/commands/oc-skills.md create mode 100644 docs/guides/opencode-setup.md create mode 100644 packages/cli/src/utils/legacy-command-guard.ts create mode 100644 scripts/legacy-xano-command.mjs diff --git a/.changeset/rapid-lions-jump.md b/.changeset/rapid-lions-jump.md new file mode 100644 index 00000000..99d242c3 --- /dev/null +++ b/.changeset/rapid-lions-jump.md @@ -0,0 +1,5 @@ +--- +"@calycode/cli": minor +--- + +refactor: **BREAKING CHANGE** rename CLI command from `xano` to `caly-xano`; update scripts, CI, and docs to use `caly-xano` diff --git a/README.md b/README.md index b067050f..e9972b10 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ pnpm install pnpm build # 4. Run any command -xano +caly-xano ``` > _(Optional)_ If you want the CLI globally available during development: @@ -61,17 +61,17 @@ I have been astonished by the shadcn/ui CLI and the core principles of code dist 1. Scaffold the registry or build it manually by obeying the schemas (https://calycode.com/schemas/registry/registry.json). ``` - xano registry-scaffold + caly-xano registry-scaffold ``` 2. Serve your registry locally or host it on an object storage (or [advanced] recreate a Xano api that would deliver the required JSON objects on demand --> this could allow you to add auth as well) ``` - xano serve-registry + caly-xano serve-registry ``` -3. Use the registry and it's content in `xano` +3. Use the registry and it's content in `caly-xano` ``` - xano registry-add --components --registry + caly-xano registry-add --components --registry ``` > [!NOTE] > **Notes:** diff --git a/docs/README.md b/docs/README.md index c87503bb..da19e9f3 100644 --- a/docs/README.md +++ b/docs/README.md @@ -41,7 +41,7 @@ pnpm install pnpm build # 4. Run any command -xano +caly-xano ``` > _(Optional)_ If you want the CLI globally available during development: @@ -65,17 +65,17 @@ I have been astonished by the shadcn/ui CLI and the core principles of code dist 1. Scaffold the registry or build it manually by obeying the schemas (https://calycode.com/schemas/registry/registry.json). ``` - xano registry-scaffold + caly-xano registry-scaffold ``` 2. Serve your registry locally or host it on an object storage (or [advanced] recreate a Xano api that would deliver the required JSON objects on demand --> this could allow you to add auth as well) ``` - xano serve-registry + caly-xano serve-registry ``` -3. Use the registry and it's content in `xano` +3. Use the registry and it's content in `caly-xano` ``` - xano registry-add --components --registry + caly-xano registry-add --components --registry ``` > [!NOTE] > **Notes:** diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 31764679..c8124206 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -1,4 +1,4 @@ -- [xano - the core command](xano.md) +- [caly-xano - the core command](xano.md) - **Commands** - [init](commands/init.md) @@ -46,6 +46,15 @@ - [oc templates status](commands/oc-templates-status.md) - [oc templates clear-cache](commands/oc-templates-clear-cache.md) +- **skills** + + - [oc skills install](commands/oc-skills-install.md) + + - [oc skills update](commands/oc-skills-update.md) + + - [oc skills status](commands/oc-skills-status.md) + + - [oc skills clear-cache](commands/oc-skills-clear-cache.md) - [oc serve](commands/oc-serve.md) diff --git a/docs/commands/backup-export.md b/docs/commands/backup-export.md index 7967dee2..dffa9943 100644 --- a/docs/commands/backup-export.md +++ b/docs/commands/backup-export.md @@ -3,7 +3,7 @@ > #### Backup Xano Workspace via Metadata API ```term -$ xano backup export [options] +$ caly-xano backup export [options] ``` ### Options @@ -18,10 +18,10 @@ $ xano backup export [options] ### backup export --help ```term -$ xano backup export --help +$ caly-xano backup export --help Backup Xano Workspace via Metadata API -Usage: xano backup export [options] +Usage: caly-xano backup export [options] Options: ├─ --instance The instance name. This is used to fetch the instance configuration. The value provided at the setup command. @@ -30,6 +30,6 @@ Options: ├─ --print-output-dir Expose usable output path for further reuse. └─ -h, --help display help for command -Run 'xano --help' for detailed usage. +Run 'caly-xano --help' for detailed usage. https://github.com/calycode/xano-tools | https://links.calycode.com/discord ``` \ No newline at end of file diff --git a/docs/commands/backup-restore.md b/docs/commands/backup-restore.md index 9aba17a3..4d901d0f 100644 --- a/docs/commands/backup-restore.md +++ b/docs/commands/backup-restore.md @@ -3,7 +3,7 @@ > #### 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. ```term -$ xano backup restore [options] +$ caly-xano backup restore [options] ``` ### Options @@ -16,10 +16,10 @@ $ xano backup restore [options] ### backup restore --help ```term -$ xano backup restore --help +$ caly-xano backup restore --help 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. -Usage: xano backup restore [options] +Usage: caly-xano backup restore [options] Options: ├─ --instance The instance name. This is used to fetch the instance configuration. The value provided at the setup command. @@ -27,6 +27,6 @@ Options: ├─ -S, --source-backup Local path to the backup file to restore. └─ -h, --help display help for command -Run 'xano --help' for detailed usage. +Run 'caly-xano --help' for detailed usage. https://github.com/calycode/xano-tools | https://links.calycode.com/discord ``` \ No newline at end of file diff --git a/docs/commands/backup.md b/docs/commands/backup.md index c2a11ee7..f2c3f121 100644 --- a/docs/commands/backup.md +++ b/docs/commands/backup.md @@ -3,15 +3,15 @@ > #### Backup and restoration operations. ```term -$ xano backup [options] +$ caly-xano backup [options] ``` ### backup --help ```term -$ xano backup --help +$ caly-xano backup --help Backup and restoration operations. -Usage: xano backup [options] [command] +Usage: caly-xano backup [options] [command] Options: └─ -h, --help display help for command @@ -21,6 +21,6 @@ Commands: ├─ restore Restore a backup to a Xano Workspace via Metadata API. DA... └─ help display help for command -Run 'xano --help' for detailed usage. +Run 'caly-xano --help' for detailed usage. https://github.com/calycode/xano-tools | https://links.calycode.com/discord ``` \ No newline at end of file diff --git a/docs/commands/context-show.md b/docs/commands/context-show.md index 5bfe7b05..61565316 100644 --- a/docs/commands/context-show.md +++ b/docs/commands/context-show.md @@ -3,19 +3,19 @@ > #### Show the current known context. ```term -$ xano context show [options] +$ caly-xano context show [options] ``` ### context show --help ```term -$ xano context show --help +$ caly-xano context show --help Show the current known context. -Usage: xano context show [options] +Usage: caly-xano context show [options] Options: └─ -h, --help display help for command -Run 'xano --help' for detailed usage. +Run 'caly-xano --help' for detailed usage. https://github.com/calycode/xano-tools | https://links.calycode.com/discord ``` \ No newline at end of file diff --git a/docs/commands/context.md b/docs/commands/context.md index 3c4b771a..538f59c5 100644 --- a/docs/commands/context.md +++ b/docs/commands/context.md @@ -3,15 +3,15 @@ > #### Context related operations. ```term -$ xano context [options] +$ caly-xano context [options] ``` ### context --help ```term -$ xano context --help +$ caly-xano context --help Context related operations. -Usage: xano context [options] [command] +Usage: caly-xano context [options] [command] Options: └─ -h, --help display help for command @@ -20,6 +20,6 @@ Commands: ├─ show Show the current known context. └─ help display help for command -Run 'xano --help' for detailed usage. +Run 'caly-xano --help' for detailed usage. https://github.com/calycode/xano-tools | https://links.calycode.com/discord ``` \ No newline at end of file diff --git a/docs/commands/generate-codegen.md b/docs/commands/generate-codegen.md index 2cad4236..5c2c9505 100644 --- a/docs/commands/generate-codegen.md +++ b/docs/commands/generate-codegen.md @@ -3,7 +3,7 @@ > #### Create a library based on the OpenAPI specification. If the openapi specification has not yet been generated, this will generate that as well as the first step. Supports **all** openapi tools generators + orval clients. ```term -$ xano generate codegen [options] +$ caly-xano generate codegen [options] ``` ### Options @@ -26,10 +26,10 @@ $ xano generate codegen [options] ### generate codegen --help ```term -$ xano generate codegen --help +$ caly-xano generate codegen --help Create a library based on the OpenAPI specification. If the openapi specification has not yet been generated, this will generate that as well as the first step. Supports **all** openapi tools generators + orval clients. -Usage: xano generate codegen [options] [passthroughArgs...] +Usage: caly-xano generate codegen [options] [passthroughArgs...] Arguments: └─ passthroughArgs Additional arguments to pass to the generator. For options for each generator see https://openapi-generator.tech/docs/usage#generate this also accepts Orval additional arguments e.g. --mock etc. See Orval docs as well: https://orval.dev/reference/configuration/full-example @@ -45,6 +45,6 @@ Options: ├─ --debug Specify this flag in order to allow logging. Logs will appear in output/_logs. Default: false └─ -h, --help display help for command -Run 'xano --help' for detailed usage. +Run 'caly-xano --help' for detailed usage. https://github.com/calycode/xano-tools | https://links.calycode.com/discord ``` \ No newline at end of file diff --git a/docs/commands/generate-docs.md b/docs/commands/generate-docs.md index 255c64cd..d8c289f6 100644 --- a/docs/commands/generate-docs.md +++ b/docs/commands/generate-docs.md @@ -3,7 +3,7 @@ > #### Collect all descriptions, and internal documentation from a Xano instance and combine it into a nice documentation suite that can be hosted on a static hosting. ```term -$ xano generate docs [options] +$ caly-xano generate docs [options] ``` ### Options @@ -24,10 +24,10 @@ $ xano generate docs [options] ### generate docs --help ```term -$ xano generate docs --help +$ caly-xano generate docs --help Collect all descriptions, and internal documentation from a Xano instance and combine it into a nice documentation suite that can be hosted on a static hosting. -Usage: xano generate docs [options] +Usage: caly-xano generate docs [options] Options: ├─ -I, --input Workspace schema file (.yaml [legacy] or .json) from a local source, if present. @@ -39,6 +39,6 @@ Options: ├─ -F, --fetch Forces fetching the workspace schema from the Xano instance via metadata API. └─ -h, --help display help for command -Run 'xano --help' for detailed usage. +Run 'caly-xano --help' for detailed usage. https://github.com/calycode/xano-tools | https://links.calycode.com/discord ``` \ No newline at end of file diff --git a/docs/commands/generate-repo.md b/docs/commands/generate-repo.md index 730ba2dc..4f6d832d 100644 --- a/docs/commands/generate-repo.md +++ b/docs/commands/generate-repo.md @@ -3,7 +3,7 @@ > #### 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. ```term -$ xano generate repo [options] +$ caly-xano generate repo [options] ``` ### Options @@ -24,10 +24,10 @@ $ xano generate repo [options] ### generate repo --help ```term -$ xano generate repo --help +$ caly-xano generate repo --help 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. -Usage: xano generate repo [options] +Usage: caly-xano generate repo [options] Options: ├─ -I, --input Workspace schema file (.yaml [legacy] or .json) from a local source, if present. @@ -39,6 +39,6 @@ Options: ├─ -F, --fetch Forces fetching the workspace schema from the Xano instance via metadata API. └─ -h, --help display help for command -Run 'xano --help' for detailed usage. +Run 'caly-xano --help' for detailed usage. https://github.com/calycode/xano-tools | https://links.calycode.com/discord ``` \ No newline at end of file diff --git a/docs/commands/generate-spec.md b/docs/commands/generate-spec.md index 31dace05..5592aef5 100644 --- a/docs/commands/generate-spec.md +++ b/docs/commands/generate-spec.md @@ -3,7 +3,7 @@ > #### 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. ```term -$ xano generate spec [options] +$ caly-xano generate spec [options] ``` ### Options @@ -24,10 +24,10 @@ $ xano generate spec [options] ### generate spec --help ```term -$ xano generate spec --help +$ caly-xano generate spec --help 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. -Usage: xano generate spec [options] +Usage: caly-xano generate spec [options] Options: ├─ --instance The instance name. This is used to fetch the instance configuration. The value provided at the setup command. @@ -39,6 +39,6 @@ Options: ├─ --include-tables Requests table schema fetching and inclusion into the generate spec. By default tables are not included. └─ -h, --help display help for command -Run 'xano --help' for detailed usage. +Run 'caly-xano --help' for detailed usage. https://github.com/calycode/xano-tools | https://links.calycode.com/discord ``` \ No newline at end of file diff --git a/docs/commands/generate-xanoscript.md b/docs/commands/generate-xanoscript.md index d9208873..e6d2eaaf 100644 --- a/docs/commands/generate-xanoscript.md +++ b/docs/commands/generate-xanoscript.md @@ -3,7 +3,7 @@ > #### 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. ```term -$ xano generate xanoscript [options] +$ caly-xano generate xanoscript [options] ``` ### Options @@ -18,10 +18,10 @@ $ xano generate xanoscript [options] ### generate xanoscript --help ```term -$ xano generate xanoscript --help +$ caly-xano generate xanoscript --help 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. -Usage: xano generate xanoscript [options] +Usage: caly-xano generate xanoscript [options] Options: ├─ --instance The instance name. This is used to fetch the instance configuration. The value provided at the setup command. @@ -30,6 +30,6 @@ Options: ├─ --print-output-dir Expose usable output path for further reuse. └─ -h, --help display help for command -Run 'xano --help' for detailed usage. +Run 'caly-xano --help' for detailed usage. https://github.com/calycode/xano-tools | https://links.calycode.com/discord ``` \ No newline at end of file diff --git a/docs/commands/generate.md b/docs/commands/generate.md index a893f0e9..b6b12c24 100644 --- a/docs/commands/generate.md +++ b/docs/commands/generate.md @@ -3,15 +3,15 @@ > #### Transforamtive operations that allow you to view you Xano through a fresh set of eyes. ```term -$ xano generate [options] +$ caly-xano generate [options] ``` ### generate --help ```term -$ xano generate --help +$ caly-xano generate --help Transforamtive operations that allow you to view you Xano through a fresh set of eyes. -Usage: xano generate [options] [command] +Usage: caly-xano generate [options] [command] Options: └─ -h, --help display help for command @@ -24,6 +24,6 @@ Commands: ├─ xanoscript Process Xano workspace into repo structure. Supports tabl... └─ help display help for command -Run 'xano --help' for detailed usage. +Run 'caly-xano --help' for detailed usage. https://github.com/calycode/xano-tools | https://links.calycode.com/discord ``` \ No newline at end of file diff --git a/docs/commands/init.md b/docs/commands/init.md index 6ed16965..02762927 100644 --- a/docs/commands/init.md +++ b/docs/commands/init.md @@ -3,7 +3,7 @@ > #### Initialize the CLI with 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. ```term -$ xano init [options] +$ caly-xano init [options] ``` ### Options @@ -20,10 +20,10 @@ $ xano init [options] ### init --help ```term -$ xano init --help +$ caly-xano init --help Initialize the CLI with 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. -Usage: xano init [options] +Usage: caly-xano init [options] Options: ├─ --name Instance name (for non-interactive setup) @@ -33,6 +33,6 @@ Options: ├─ --no-set-current Flag to not set this instance as the current context, by default it is set. └─ -h, --help display help for command -Run 'xano --help' for detailed usage. +Run 'caly-xano --help' for detailed usage. https://github.com/calycode/xano-tools | https://links.calycode.com/discord ``` \ No newline at end of file diff --git a/docs/commands/oc-init.md b/docs/commands/oc-init.md index d09fab07..f72c090f 100644 --- a/docs/commands/oc-init.md +++ b/docs/commands/oc-init.md @@ -3,7 +3,7 @@ > #### Initialize OpenCode native host integration and configuration for use with the CalyCode extension. ```term -$ xano oc init [options] +$ caly-xano oc init [options] ``` ### Options @@ -14,16 +14,16 @@ $ xano oc init [options] ### oc init --help ```term -$ xano oc init --help +$ caly-xano oc init --help Initialize OpenCode native host integration and configuration for use with the CalyCode extension. -Usage: xano oc init [options] +Usage: caly-xano oc init [options] Options: ├─ -f, --force Force overwrite existing configuration files ├─ --skip-config Skip installing OpenCode configuration templates └─ -h, --help display help for command -Run 'xano --help' for detailed usage. +Run 'caly-xano --help' for detailed usage. https://github.com/calycode/xano-tools | https://links.calycode.com/discord ``` \ No newline at end of file diff --git a/docs/commands/oc-native-host.md b/docs/commands/oc-native-host.md index 95f6ac06..ca77fe6c 100644 --- a/docs/commands/oc-native-host.md +++ b/docs/commands/oc-native-host.md @@ -3,19 +3,19 @@ > #### Internal command used by Chrome Native Messaging to communicate with the extension. ```term -$ xano oc native-host [options] +$ caly-xano oc native-host [options] ``` ### oc native-host --help ```term -$ xano oc native-host --help +$ caly-xano oc native-host --help Internal command used by Chrome Native Messaging to communicate with the extension. -Usage: xano oc native-host [options] +Usage: caly-xano oc native-host [options] Options: └─ -h, --help display help for command -Run 'xano --help' for detailed usage. +Run 'caly-xano --help' for detailed usage. https://github.com/calycode/xano-tools | https://links.calycode.com/discord ``` \ No newline at end of file diff --git a/docs/commands/oc-run.md b/docs/commands/oc-run.md index 4b0406d2..d113c929 100644 --- a/docs/commands/oc-run.md +++ b/docs/commands/oc-run.md @@ -3,15 +3,15 @@ > #### Run any OpenCode CLI command (default) ```term -$ xano oc run [options] +$ caly-xano oc run [options] ``` ### oc run --help ```term -$ xano oc run --help +$ caly-xano oc run --help Run any OpenCode CLI command (default) -Usage: xano oc run [options] [args...] +Usage: caly-xano oc run [options] [args...] Arguments: └─ args Arguments to pass to OpenCode CLI @@ -19,6 +19,6 @@ Arguments: Options: └─ -h, --help display help for command -Run 'xano --help' for detailed usage. +Run 'caly-xano --help' for detailed usage. https://github.com/calycode/xano-tools | https://links.calycode.com/discord ``` \ No newline at end of file diff --git a/docs/commands/oc-serve.md b/docs/commands/oc-serve.md index 5923700f..83df2d1c 100644 --- a/docs/commands/oc-serve.md +++ b/docs/commands/oc-serve.md @@ -3,7 +3,7 @@ > #### Serve the OpenCode AI server locally. ```term -$ xano oc serve [options] +$ caly-xano oc serve [options] ``` ### Options @@ -14,16 +14,16 @@ $ xano oc serve [options] ### oc serve --help ```term -$ xano oc serve --help +$ caly-xano oc serve --help Serve the OpenCode AI server locally. -Usage: xano oc serve [options] +Usage: caly-xano oc serve [options] Options: ├─ --port Port to run the OpenCode server on (default: 4096) ├─ -d, --detach Run the server in the background (detached mode) └─ -h, --help display help for command -Run 'xano --help' for detailed usage. +Run 'caly-xano --help' for detailed usage. https://github.com/calycode/xano-tools | https://links.calycode.com/discord ``` \ No newline at end of file diff --git a/docs/commands/oc-skills-clear-cache.md b/docs/commands/oc-skills-clear-cache.md new file mode 100644 index 00000000..433b7058 --- /dev/null +++ b/docs/commands/oc-skills-clear-cache.md @@ -0,0 +1,21 @@ +# oc skills clear-cache +>[!NOTE|label:Description] +> #### Clear the skills cache (skills will be re-downloaded on next install). + +```term +$ caly-xano oc skills clear-cache [options] +``` + +### oc skills clear-cache --help +```term +$ caly-xano oc skills clear-cache --help +Clear the skills cache (skills will be re-downloaded on next install). + +Usage: caly-xano oc skills clear-cache [options] + +Options: + └─ -h, --help display help for command + +Run 'caly-xano --help' for detailed usage. +https://github.com/calycode/xano-tools | https://links.calycode.com/discord +``` \ No newline at end of file diff --git a/docs/commands/oc-skills-install.md b/docs/commands/oc-skills-install.md new file mode 100644 index 00000000..89e68f27 --- /dev/null +++ b/docs/commands/oc-skills-install.md @@ -0,0 +1,26 @@ +# oc skills install +>[!NOTE|label:Description] +> #### Install or reinstall Xano skills for AI agents. + +```term +$ caly-xano oc skills install [options] +``` +### Options + +#### -f, --force +**Description:** Force overwrite existing skills + +### oc skills install --help +```term +$ caly-xano oc skills install --help +Install or reinstall Xano skills for AI agents. + +Usage: caly-xano oc skills install [options] + +Options: + ├─ -f, --force Force overwrite existing skills + └─ -h, --help display help for command + +Run 'caly-xano --help' for detailed usage. +https://github.com/calycode/xano-tools | https://links.calycode.com/discord +``` \ No newline at end of file diff --git a/docs/commands/oc-skills-status.md b/docs/commands/oc-skills-status.md new file mode 100644 index 00000000..a643a86d --- /dev/null +++ b/docs/commands/oc-skills-status.md @@ -0,0 +1,21 @@ +# oc skills status +>[!NOTE|label:Description] +> #### Show the status of installed skills. + +```term +$ caly-xano oc skills status [options] +``` + +### oc skills status --help +```term +$ caly-xano oc skills status --help +Show the status of installed skills. + +Usage: caly-xano oc skills status [options] + +Options: + └─ -h, --help display help for command + +Run 'caly-xano --help' for detailed usage. +https://github.com/calycode/xano-tools | https://links.calycode.com/discord +``` \ No newline at end of file diff --git a/docs/commands/oc-skills-update.md b/docs/commands/oc-skills-update.md new file mode 100644 index 00000000..8c7ea1ee --- /dev/null +++ b/docs/commands/oc-skills-update.md @@ -0,0 +1,21 @@ +# oc skills update +>[!NOTE|label:Description] +> #### Update skills by fetching the latest versions from GitHub. + +```term +$ caly-xano oc skills update [options] +``` + +### oc skills update --help +```term +$ caly-xano oc skills update --help +Update skills by fetching the latest versions from GitHub. + +Usage: caly-xano oc skills update [options] + +Options: + └─ -h, --help display help for command + +Run 'caly-xano --help' for detailed usage. +https://github.com/calycode/xano-tools | https://links.calycode.com/discord +``` \ No newline at end of file diff --git a/docs/commands/oc-skills.md b/docs/commands/oc-skills.md new file mode 100644 index 00000000..041d8578 --- /dev/null +++ b/docs/commands/oc-skills.md @@ -0,0 +1,28 @@ +# oc skills +>[!NOTE|label:Description] +> #### Manage Xano skills for AI agents (database optimization, security, best practices). + +```term +$ caly-xano oc skills [options] +``` + +### oc skills --help +```term +$ caly-xano oc skills --help +Manage Xano skills for AI agents (database optimization, security, best practices). + +Usage: caly-xano oc skills [options] [command] + +Options: + └─ -h, --help display help for command + +Commands: + ├─ install Install or reinstall Xano skills for AI agents. + ├─ update Update skills by fetching the latest versions from GitHub. + ├─ status Show the status of installed skills. + ├─ clear-cache Clear the skills cache (skills will be re-downloaded on n... + └─ help display help for command + +Run 'caly-xano --help' for detailed usage. +https://github.com/calycode/xano-tools | https://links.calycode.com/discord +``` \ No newline at end of file diff --git a/docs/commands/oc-templates-clear-cache.md b/docs/commands/oc-templates-clear-cache.md index 851a052c..b438875f 100644 --- a/docs/commands/oc-templates-clear-cache.md +++ b/docs/commands/oc-templates-clear-cache.md @@ -3,19 +3,19 @@ > #### Clear the template cache (templates will be re-downloaded on next install). ```term -$ xano oc templates clear-cache [options] +$ caly-xano oc templates clear-cache [options] ``` ### oc templates clear-cache --help ```term -$ xano oc templates clear-cache --help +$ caly-xano oc templates clear-cache --help Clear the template cache (templates will be re-downloaded on next install). -Usage: xano oc templates clear-cache [options] +Usage: caly-xano oc templates clear-cache [options] Options: └─ -h, --help display help for command -Run 'xano --help' for detailed usage. +Run 'caly-xano --help' for detailed usage. https://github.com/calycode/xano-tools | https://links.calycode.com/discord ``` \ No newline at end of file diff --git a/docs/commands/oc-templates-install.md b/docs/commands/oc-templates-install.md index 14d84c04..c2149b35 100644 --- a/docs/commands/oc-templates-install.md +++ b/docs/commands/oc-templates-install.md @@ -3,7 +3,7 @@ > #### Install or reinstall OpenCode configuration templates. ```term -$ xano oc templates install [options] +$ caly-xano oc templates install [options] ``` ### Options @@ -12,15 +12,15 @@ $ xano oc templates install [options] ### oc templates install --help ```term -$ xano oc templates install --help +$ caly-xano oc templates install --help Install or reinstall OpenCode configuration templates. -Usage: xano oc templates install [options] +Usage: caly-xano oc templates install [options] Options: ├─ -f, --force Force overwrite existing configuration files └─ -h, --help display help for command -Run 'xano --help' for detailed usage. +Run 'caly-xano --help' for detailed usage. https://github.com/calycode/xano-tools | https://links.calycode.com/discord ``` \ No newline at end of file diff --git a/docs/commands/oc-templates-status.md b/docs/commands/oc-templates-status.md index 48c3247e..8b3138c1 100644 --- a/docs/commands/oc-templates-status.md +++ b/docs/commands/oc-templates-status.md @@ -3,19 +3,19 @@ > #### Show the status of installed OpenCode templates. ```term -$ xano oc templates status [options] +$ caly-xano oc templates status [options] ``` ### oc templates status --help ```term -$ xano oc templates status --help +$ caly-xano oc templates status --help Show the status of installed OpenCode templates. -Usage: xano oc templates status [options] +Usage: caly-xano oc templates status [options] Options: └─ -h, --help display help for command -Run 'xano --help' for detailed usage. +Run 'caly-xano --help' for detailed usage. https://github.com/calycode/xano-tools | https://links.calycode.com/discord ``` \ No newline at end of file diff --git a/docs/commands/oc-templates-update.md b/docs/commands/oc-templates-update.md index 4c74c824..66c3e5c8 100644 --- a/docs/commands/oc-templates-update.md +++ b/docs/commands/oc-templates-update.md @@ -3,19 +3,19 @@ > #### Update templates by fetching the latest versions from GitHub. ```term -$ xano oc templates update [options] +$ caly-xano oc templates update [options] ``` ### oc templates update --help ```term -$ xano oc templates update --help +$ caly-xano oc templates update --help Update templates by fetching the latest versions from GitHub. -Usage: xano oc templates update [options] +Usage: caly-xano oc templates update [options] Options: └─ -h, --help display help for command -Run 'xano --help' for detailed usage. +Run 'caly-xano --help' for detailed usage. https://github.com/calycode/xano-tools | https://links.calycode.com/discord ``` \ No newline at end of file diff --git a/docs/commands/oc-templates.md b/docs/commands/oc-templates.md index c806e207..15ab415e 100644 --- a/docs/commands/oc-templates.md +++ b/docs/commands/oc-templates.md @@ -3,15 +3,15 @@ > #### Manage OpenCode configuration templates (agents, commands, instructions). ```term -$ xano oc templates [options] +$ caly-xano oc templates [options] ``` ### oc templates --help ```term -$ xano oc templates --help +$ caly-xano oc templates --help Manage OpenCode configuration templates (agents, commands, instructions). -Usage: xano oc templates [options] [command] +Usage: caly-xano oc templates [options] [command] Options: └─ -h, --help display help for command @@ -23,6 +23,6 @@ Commands: ├─ clear-cache Clear the template cache (templates will be re-downloaded... └─ help display help for command -Run 'xano --help' for detailed usage. +Run 'caly-xano --help' for detailed usage. https://github.com/calycode/xano-tools | https://links.calycode.com/discord ``` \ No newline at end of file diff --git a/docs/commands/oc.md b/docs/commands/oc.md index a3770096..336a193b 100644 --- a/docs/commands/oc.md +++ b/docs/commands/oc.md @@ -6,18 +6,18 @@ License: MIT (see LICENSES/opencode-ai.txt) ```term -$ xano oc [options] +$ caly-xano oc [options] ``` ### oc --help ```term -$ xano oc --help +$ caly-xano oc --help Manage OpenCode AI integration and tools. Powered by OpenCode - The open source AI coding agent. GitHub: https://github.com/anomalyco/opencode License: MIT (see LICENSES/opencode-ai.txt) -Usage: xano oc|opencode [options] [command] +Usage: caly-xano oc|opencode [options] [command] Options: └─ -h, --help display help for command @@ -25,9 +25,10 @@ Options: Commands: ├─ init Initialize OpenCode native host integration and configura... ├─ templates Manage OpenCode configuration templates (agents, commands... + ├─ skills Manage Xano skills for AI agents (database optimization, ... ├─ serve Serve the OpenCode AI server locally. └─ help display help for command -Run 'xano --help' for detailed usage. +Run 'caly-xano --help' for detailed usage. https://github.com/calycode/xano-tools | https://links.calycode.com/discord ``` \ No newline at end of file diff --git a/docs/commands/registry-add.md b/docs/commands/registry-add.md index 8d79d490..5e9cd1db 100644 --- a/docs/commands/registry-add.md +++ b/docs/commands/registry-add.md @@ -3,7 +3,7 @@ > #### Add a prebuilt component to the current Xano context, essentially by pushing an item from the registry to the Xano instance. ```term -$ xano registry add [options] +$ caly-xano registry add [options] ``` ### Options @@ -18,10 +18,10 @@ $ xano registry add [options] ### registry add --help ```term -$ xano registry add --help +$ caly-xano registry add --help Add a prebuilt component to the current Xano context, essentially by pushing an item from the registry to the Xano instance. -Usage: xano registry add [options] [components...] +Usage: caly-xano registry add [options] [components...] Arguments: └─ components Space delimited list of components to add to your Xano instance. @@ -33,6 +33,6 @@ Options: ├─ --registry URL to the component registry. Default: http://localhost:5500/registry/definitions └─ -h, --help display help for command -Run 'xano --help' for detailed usage. +Run 'caly-xano --help' for detailed usage. https://github.com/calycode/xano-tools | https://links.calycode.com/discord ``` \ No newline at end of file diff --git a/docs/commands/registry-scaffold.md b/docs/commands/registry-scaffold.md index e6570dfb..57189358 100644 --- a/docs/commands/registry-scaffold.md +++ b/docs/commands/registry-scaffold.md @@ -3,7 +3,7 @@ > #### 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. ```term -$ xano registry scaffold [options] +$ caly-xano registry scaffold [options] ``` ### Options @@ -14,16 +14,16 @@ $ xano registry scaffold [options] ### registry scaffold --help ```term -$ xano registry scaffold --help +$ caly-xano registry scaffold --help 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. -Usage: xano registry scaffold [options] +Usage: caly-xano registry scaffold [options] Options: ├─ --output Local output path for the registry ├─ --instance The instance name. This is used to fetch the instance configuration. The value provided at the setup command. └─ -h, --help display help for command -Run 'xano --help' for detailed usage. +Run 'caly-xano --help' for detailed usage. https://github.com/calycode/xano-tools | https://links.calycode.com/discord ``` \ No newline at end of file diff --git a/docs/commands/registry.md b/docs/commands/registry.md index 5ac21592..18ba95d5 100644 --- a/docs/commands/registry.md +++ b/docs/commands/registry.md @@ -3,15 +3,15 @@ > #### Registry related operations. Use this when you wish to add prebuilt components to your Xano instance. ```term -$ xano registry [options] +$ caly-xano registry [options] ``` ### registry --help ```term -$ xano registry --help +$ caly-xano registry --help Registry related operations. Use this when you wish to add prebuilt components to your Xano instance. -Usage: xano registry [options] [command] +Usage: caly-xano registry [options] [command] Options: └─ -h, --help display help for command @@ -21,6 +21,6 @@ Commands: ├─ scaffold Scaffold a Xano registry folder with a sample component. ... └─ help display help for command -Run 'xano --help' for detailed usage. +Run 'caly-xano --help' for detailed usage. https://github.com/calycode/xano-tools | https://links.calycode.com/discord ``` \ No newline at end of file diff --git a/docs/commands/serve-registry.md b/docs/commands/serve-registry.md index 20dd3ce3..2e9c323d 100644 --- a/docs/commands/serve-registry.md +++ b/docs/commands/serve-registry.md @@ -3,7 +3,7 @@ > #### Serve the registry locally. This allows you to actually use your registry without deploying it to any remote host. ```term -$ xano serve registry [options] +$ caly-xano serve registry [options] ``` ### Options @@ -16,10 +16,10 @@ $ xano serve registry [options] ### serve registry --help ```term -$ xano serve registry --help +$ caly-xano serve registry --help Serve the registry locally. This allows you to actually use your registry without deploying it to any remote host. -Usage: xano serve registry [options] +Usage: caly-xano serve registry [options] Options: ├─ --root Where did you put your registry? (Local path to the registry directory) @@ -27,6 +27,6 @@ Options: ├─ --cors Do you want to enable CORS? By default false. └─ -h, --help display help for command -Run 'xano --help' for detailed usage. +Run 'caly-xano --help' for detailed usage. https://github.com/calycode/xano-tools | https://links.calycode.com/discord ``` \ No newline at end of file diff --git a/docs/commands/serve-spec.md b/docs/commands/serve-spec.md index 3a55508f..6cddd27b 100644 --- a/docs/commands/serve-spec.md +++ b/docs/commands/serve-spec.md @@ -3,7 +3,7 @@ > #### Serve the Open API specification locally for quick visual check, or to test your APIs via the Scalar API reference. ```term -$ xano serve spec [options] +$ caly-xano serve spec [options] ``` ### Options @@ -24,10 +24,10 @@ $ xano serve spec [options] ### serve spec --help ```term -$ xano serve spec --help +$ caly-xano serve spec --help Serve the Open API specification locally for quick visual check, or to test your APIs via the Scalar API reference. -Usage: xano serve spec [options] +Usage: caly-xano serve spec [options] Options: ├─ --instance The instance name. This is used to fetch the instance configuration. The value provided at the setup command. @@ -39,6 +39,6 @@ Options: ├─ --cors Do you want to enable CORS? By default false. └─ -h, --help display help for command -Run 'xano --help' for detailed usage. +Run 'caly-xano --help' for detailed usage. https://github.com/calycode/xano-tools | https://links.calycode.com/discord ``` \ No newline at end of file diff --git a/docs/commands/serve.md b/docs/commands/serve.md index 133e187a..9a34ddbc 100644 --- a/docs/commands/serve.md +++ b/docs/commands/serve.md @@ -3,15 +3,15 @@ > #### Serve locally available assets for quick preview or local reuse. ```term -$ xano serve [options] +$ caly-xano serve [options] ``` ### serve --help ```term -$ xano serve --help +$ caly-xano serve --help Serve locally available assets for quick preview or local reuse. -Usage: xano serve [options] [command] +Usage: caly-xano serve [options] [command] Options: └─ -h, --help display help for command @@ -21,6 +21,6 @@ Commands: ├─ spec Serve the Open API specification locally for quick visual... └─ help display help for command -Run 'xano --help' for detailed usage. +Run 'caly-xano --help' for detailed usage. https://github.com/calycode/xano-tools | https://links.calycode.com/discord ``` \ No newline at end of file diff --git a/docs/commands/test-run.md b/docs/commands/test-run.md index 6d3f2840..0dfb35e5 100644 --- a/docs/commands/test-run.md +++ b/docs/commands/test-run.md @@ -3,7 +3,7 @@ > #### Run an API test suite. Requires a test config file (.json or .js). Schema: https://calycode.com/schemas/testing/config.json | Full guide: https://calycode.github.io/xano-tools/#/guides/testing ```term -$ xano test run [options] +$ caly-xano test run [options] ``` ### Options @@ -30,10 +30,10 @@ $ xano test run [options] ### test run --help ```term -$ xano test run --help +$ caly-xano test run --help Run an API test suite. Requires a test config file (.json or .js). Schema: https://calycode.com/schemas/testing/config.json | Full guide: https://calycode.github.io/xano-tools/#/guides/testing -Usage: xano test run [options] +Usage: caly-xano test run [options] Options: ├─ --instance The instance name. This is used to fetch the instance configuration. The value provided at the setup command. @@ -48,6 +48,6 @@ Options: ├─ --fail-on-warnings In CI mode, also fail if there are warnings (not just errors). └─ -h, --help display help for command -Run 'xano --help' for detailed usage. +Run 'caly-xano --help' for detailed usage. https://github.com/calycode/xano-tools | https://links.calycode.com/discord ``` \ No newline at end of file diff --git a/docs/commands/test.md b/docs/commands/test.md index c63a52f5..2c5ee50d 100644 --- a/docs/commands/test.md +++ b/docs/commands/test.md @@ -3,15 +3,15 @@ > #### Set of test related operations for the Xano CLI, these help you build a reliable system. ```term -$ xano test [options] +$ caly-xano test [options] ``` ### test --help ```term -$ xano test --help +$ caly-xano test --help Set of test related operations for the Xano CLI, these help you build a reliable system. -Usage: xano test [options] [command] +Usage: caly-xano test [options] [command] Options: └─ -h, --help display help for command @@ -20,6 +20,6 @@ Commands: ├─ run Run an API test suite. Requires a test config file (.json... └─ help display help for command -Run 'xano --help' for detailed usage. +Run 'caly-xano --help' for detailed usage. https://github.com/calycode/xano-tools | https://links.calycode.com/discord ``` \ No newline at end of file diff --git a/docs/guides/git-workflow.md b/docs/guides/git-workflow.md index 369e4897..823fedda 100644 --- a/docs/guides/git-workflow.md +++ b/docs/guides/git-workflow.md @@ -30,7 +30,7 @@ Xano Tools enables Git-based version control for your Xano backend by: npm install -g @calycode/cli # Initialize with your Xano instance -xano init +caly-xano init # Follow prompts to configure: # - Instance name @@ -43,7 +43,7 @@ xano init ```bash # Generate complete repository structure -xano generate repo \ +caly-xano generate repo \ --instance production \ --workspace main \ --branch live @@ -68,7 +68,7 @@ git push -u origin main ### The `generate repo` Command ```bash -xano generate repo [options] +caly-xano generate repo [options] ``` **Options:** @@ -107,7 +107,7 @@ project/ For just XanoScript (lighter weight): ```bash -xano generate xanoscript \ +caly-xano generate xanoscript \ --instance production \ --workspace main \ --branch live @@ -151,7 +151,7 @@ git checkout -b feature/new-api # (Use Calycode Extension for branch management) # Export changes -xano generate xanoscript --branch dev +caly-xano generate xanoscript --branch dev # Commit git add . @@ -167,7 +167,7 @@ git commit -m "Add new API endpoints" git pull origin develop # Check for updates from Xano -xano generate xanoscript --branch develop +caly-xano generate xanoscript --branch develop # Review changes git status @@ -178,7 +178,7 @@ git diff ```bash # Export your changes -xano generate repo --branch develop +caly-xano generate repo --branch develop # Review what changed git status @@ -200,13 +200,13 @@ git push origin feature/user-profile ```bash # Run tests -xano test run -c ./tests/config.json --branch develop --ci +caly-xano test run -c ./tests/config.json --branch develop --ci # Generate fresh docs -xano generate docs +caly-xano generate docs # Final export -xano generate repo --branch develop +caly-xano generate repo --branch develop # Commit any doc changes git add . @@ -237,18 +237,18 @@ jobs: with: node-version: '20' - - name: Install Xano CLI - run: npm install -g @calycode/cli + - name: Install Xano CLI + run: npm install -g @calycode/cli - - name: Generate Repository - env: - XANO_TOKEN_PRODUCTION: ${{ secrets.XANO_TOKEN }} - run: | - xano generate repo \ - --instance production \ - --workspace main \ - --branch live \ - --fetch + - name: Generate Repository + env: + XANO_TOKEN_PRODUCTION: ${{ secrets.XANO_TOKEN }} + run: | + caly-xano generate repo \ + --instance production \ + --workspace main \ + --branch live \ + --fetch - name: Check for Changes id: changes @@ -287,22 +287,22 @@ jobs: with: node-version: '20' - - name: Install Xano CLI - run: npm install -g @calycode/cli - - - name: Run Tests - env: - XANO_TOKEN_STAGING: ${{ secrets.XANO_TOKEN_STAGING }} - XANO_TEST_EMAIL: ${{ secrets.TEST_EMAIL }} - XANO_TEST_PASSWORD: ${{ secrets.TEST_PASSWORD }} - run: | - xano test run \ - -c ./tests/config.json \ - --instance staging \ - --workspace main \ - --branch staging \ - --all \ - --ci + - name: Install Xano CLI + run: npm install -g @calycode/cli + + - name: Run Tests + env: + XANO_TOKEN_STAGING: ${{ secrets.XANO_TOKEN_STAGING }} + XANO_TEST_EMAIL: ${{ secrets.TEST_EMAIL }} + XANO_TEST_PASSWORD: ${{ secrets.TEST_PASSWORD }} + run: | + caly-xano test run \ + -c ./tests/config.json \ + --instance staging \ + --workspace main \ + --branch staging \ + --all \ + --ci ``` ### Documentation Deployment @@ -325,13 +325,13 @@ jobs: with: node-version: '20' - - name: Install Xano CLI - run: npm install -g @calycode/cli + - name: Install Xano CLI + run: npm install -g @calycode/cli - - name: Generate Documentation - env: - XANO_TOKEN_PRODUCTION: ${{ secrets.XANO_TOKEN }} - run: xano generate docs + - name: Generate Documentation + env: + XANO_TOKEN_PRODUCTION: ${{ secrets.XANO_TOKEN }} + run: caly-xano generate docs - name: Deploy to GitHub Pages uses: peaceiris/actions-gh-pages@v3 @@ -425,7 +425,7 @@ XANO_TOKEN_STAGING=your-staging-token Before merging: - [ ] XanoScript exported and committed -- [ ] Tests pass (`xano test run --ci`) +- [ ] Tests pass (`caly-xano test run --ci`) - [ ] Documentation updated - [ ] No secrets in code - [ ] Follows naming conventions @@ -437,7 +437,7 @@ Before merging: | Issue | Solution | | ----------------------- | --------------------------------------- | -| "Instance not found" | Run `xano init` to configure | +| "Instance not found" | Run `caly-xano init` to configure | | "Authentication failed" | Check `XANO_TOKEN_*` env vars | | Merge conflicts in JSON | Regenerate from Xano, resolve manually | | Missing XanoScript | Ensure Xano 2.0+ for XanoScript support | @@ -449,7 +449,7 @@ Before merging: git checkout -- . # Fresh export from Xano -xano generate repo --fetch +caly-xano generate repo --fetch # Review and commit git add . diff --git a/docs/guides/opencode-setup.md b/docs/guides/opencode-setup.md new file mode 100644 index 00000000..56f3579c --- /dev/null +++ b/docs/guides/opencode-setup.md @@ -0,0 +1,429 @@ +# OpenCode AI Agent Setup + +This guide covers setting up and using the OpenCode AI agent integration with the CalyCode CLI for AI-assisted Xano development. + +> **Note:** The CLI binary name changed from `xano` to `caly-xano` in v2.0. All commands below use `caly-xano`. If you're using an older version, replace `caly-xano` with `xano`. + +> [!NOTE] +> CalyCode integrates with [OpenCode](https://opencode.ai), an open-source AI coding agent licensed under MIT. CalyCode is **not affiliated with, maintained by, or endorsed by** the OpenCode project. We simply leverage their excellent open-source tooling to provide AI-assisted Xano development capabilities. + +## Table of Contents + +- [Overview](#overview) +- [Quick Start](#quick-start) +- [Setup Command](#setup-command) +- [Running OpenCode](#running-opencode) +- [Agents & Slash Commands](#agents--slash-commands) +- [Skills](#skills) +- [Configuration Files](#configuration-files) +- [Native Host for Browser Extension](#native-host-for-browser-extension) +- [Troubleshooting](#troubleshooting) + +## Overview + +The CalyCode CLI integrates with [OpenCode](https://opencode.ai), an open-source AI coding agent. This integration provides: + +- **Specialized Xano Agents** - AI agents trained for XanoScript development +- **Slash Commands** - Quick actions for common Xano tasks +- **Skills** - Domain-specific knowledge for database design, security, and performance +- **Browser Extension Support** - Native messaging host for the CalyCode Chrome extension + +## Quick Start + +```bash +# 1. Install the CLI globally +npm install -g @calycode/cli + +# 2. Set up OpenCode with agents, commands, and skills +caly-xano oc setup + +# 3. Run OpenCode interactively +caly-xano oc run + +# 4. Or run with a specific agent +caly-xano oc run "@xano-planner Plan a user authentication system" +``` + +## Setup Command + +The `caly-xano oc setup` command installs everything needed for AI-assisted development: + +```bash +caly-xano oc setup [options] +``` + +### Options + +| Option | Description | +| ---------------- | ------------------------------------------------ | +| `--force` | Re-download and overwrite existing configuration | +| `--skip-config` | Skip template/skill installation | +| `--extension-id` | Register additional Chrome extension IDs | + +### What Gets Installed + +The setup command installs files to `~/.calycode/opencode/`: + +``` +~/.calycode/opencode/ +├── opencode.json # OpenCode configuration +├── AGENTS.md # Global agent instructions +├── agents/ # Specialized agents +│ ├── xano-planner.md +│ ├── xano-table-designer.md +│ ├── xano-function-writer.md +│ ├── xano-api-writer.md +│ ├── xano-addon-writer.md +│ ├── xano-task-writer.md +│ ├── xano-ai-builder.md +│ └── ... +├── commands/ # Slash commands +│ ├── xano-plan.md +│ ├── xano-table.md +│ ├── xano-function.md +│ ├── xano-api.md +│ └── ... +└── skills/ # Domain-specific knowledge + ├── xano-database-best-practices/ + ├── xano-query-performance/ + ├── xano-schema-design/ + ├── xano-security/ + ├── xano-data-access/ + ├── xano-monitoring/ + └── caly-xano-cli/ +``` + +### Update Templates + +To get the latest agents, commands, and skills: + +```bash +# Force re-download all templates +caly-xano oc setup --force + +# Or update just templates +caly-xano oc update +``` + +## Running OpenCode + +### Interactive Mode + +Start an interactive AI coding session: + +```bash +# Start OpenCode in the current directory +caly-xano oc run + +# Start in a specific project directory +caly-xano oc run --workdir /path/to/project +``` + +### With Initial Prompt + +Run with a specific task or agent: + +```bash +# Use a specialized agent +caly-xano oc run "@xano-planner Design a blog backend with posts and comments" + +# Use a slash command +caly-xano oc run "/xano-table Create a users table with email and password" + +# Simple prompt +caly-xano oc run "Help me understand this XanoScript function" +``` + +### Server Mode + +Run OpenCode as an HTTP server for programmatic access: + +```bash +# Start server on default port (4096) +caly-xano oc serve + +# Start on a specific port +caly-xano oc serve --port 8080 + +# Start in background (detached) +caly-xano oc serve --detach +``` + +## Agents & Slash Commands + +### Specialized Agents + +Use `@agent-name` to delegate to specialized agents: + +| Agent | Use Case | +| ----------------------- | ------------------------------------------------ | +| `@xano-planner` | Plan features and create implementation roadmaps | +| `@xano-table-designer` | Design database tables with schemas and indexes | +| `@xano-function-writer` | Create reusable functions with business logic | +| `@xano-api-writer` | Create REST API endpoints | +| `@xano-addon-writer` | Create addons for related data fetching | +| `@xano-task-writer` | Create scheduled tasks for background processing | +| `@xano-ai-builder` | Build AI agents, tools, and MCP servers | +| `@xano-expert` | General Xano expertise and troubleshooting | +| `@debug-helper` | Debug API and function issues | + +### Examples + +```bash +# Plan a feature +caly-xano oc run "@xano-planner Plan a subscription billing system with Stripe" + +# Design a table +caly-xano oc run "@xano-table-designer Create a products table for an e-commerce store" + +# Create an API +caly-xano oc run "@xano-api-writer Create CRUD endpoints for user management" + +# Debug an issue +caly-xano oc run "@debug-helper My API is returning 500 errors on POST requests" +``` + +### Slash Commands + +Use `/command` for quick actions: + +| Command | Description | +| ---------------- | ---------------------------------------- | +| `/xano-plan` | Plan a feature or project implementation | +| `/xano-table` | Create a XanoScript database table | +| `/xano-function` | Create a XanoScript function | +| `/xano-api` | Create a XanoScript API endpoint | +| `/xano-addon` | Create a XanoScript addon | +| `/xano-task` | Create a XanoScript scheduled task | +| `/xano-ai` | Build AI agents, tools, or MCP servers | +| `/xano-docs` | Search Xano documentation | +| `/debug-api` | Debug an API endpoint | +| `/generate-sdk` | Generate TypeScript SDK from OpenAPI | + +### Examples + +```bash +# Create a table +caly-xano oc run "/xano-table users with email, password_hash, role enum (admin, user)" + +# Create a function +caly-xano oc run "/xano-function calculate_order_total that sums line items with tax" + +# Create an API +caly-xano oc run "/xano-api POST /checkout that processes payment and creates order" +``` + +## Skills + +Skills provide domain-specific knowledge that agents can reference. They are loaded automatically when relevant tasks are detected. + +### Available Skills + +| Skill | Description | +| ------------------------------ | ---------------------------------------------- | +| `xano-database-best-practices` | PostgreSQL best practices for Xano | +| `xano-query-performance` | Query optimization, N+1 prevention, indexing | +| `xano-schema-design` | Schema normalization, data types, constraints | +| `xano-security` | Row Level Security, injection prevention, auth | +| `xano-data-access` | Addons, batch operations, caching patterns | +| `xano-monitoring` | Query Analytics, debugging slow queries | +| `caly-xano-cli` | CalyCode CLI commands and workflows | + +### Skill Selection Guide + +| Task | Primary Skill | Supporting Skills | +| -------------------- | ------------------------ | ------------------------------ | +| New table design | `xano-schema-design` | `xano-database-best-practices` | +| Slow API response | `xano-query-performance` | `xano-monitoring` | +| N+1 query issues | `xano-query-performance` | `xano-data-access` | +| Security audit | `xano-security` | `xano-data-access` | +| CLI commands | `caly-xano-cli` | - | +| Production debugging | `xano-monitoring` | `xano-query-performance` | + +### Using Skills Explicitly + +You can reference skills in your prompts: + +```bash +caly-xano oc run "Use the xano-security skill to review this login endpoint" + +caly-xano oc run "Apply xano-query-performance patterns to optimize this data fetching" +``` + +## Configuration Files + +### opencode.json + +The main OpenCode configuration at `~/.calycode/opencode/opencode.json`: + +```json +{ + "$schema": "https://opencode.ai/config.json", + "model": "anthropic/claude-sonnet-4-20250514", + "small_model": "anthropic/claude-haiku-4-20250514", + "autoupdate": true, + "instructions": ["~/.config/opencode/AGENTS.md"], + "permission": { + "edit": "ask", + "bash": { + "*": "ask", + "git status": "allow", + "git diff": "allow", + "git log": "allow", + "npm test": "allow", + "pnpm test": "allow" + } + } +} +``` + +### Customizing Configuration + +You can modify the configuration to: + +- Change the default model +- Add custom instructions +- Adjust permission settings +- Enable auto-approve for specific commands + +### Environment Variables + +| Variable | Description | +| ------------------------- | --------------------------------------------------------- | +| `OPENCODE_CONFIG_DIR` | Override OpenCode config directory | +| `CALY_EXTRA_CORS_ORIGINS` | Additional CORS origins for server mode (comma-separated) | + +## Native Host for Browser Extension + +The CLI can act as a native messaging host for the CalyCode Chrome extension, enabling browser-to-local communication. + +### How It Works + +1. Browser extension sends messages via Chrome's Native Messaging API +2. The native host (CLI) receives and processes requests +3. OpenCode server can be started/stopped from the browser +4. Results are returned to the extension + +### Setup + +The native host is automatically configured during `caly-xano oc setup`. For manual setup: + +```bash +# Install native host manifest +caly-xano oc setup + +# The manifest is created at: +# Windows: %USERPROFILE%\.calycode\com.calycode.host.json +# macOS: ~/Library/Application Support/Google/Chrome/NativeMessagingHosts/ +# Linux: ~/.config/google-chrome/NativeMessagingHosts/ +``` + +### Testing Native Host + +```bash +# Start native host directly (for debugging) +caly-xano oc native-host + +# The native host listens for JSON messages on stdin +# and responds on stdout using Chrome's native messaging protocol +``` + +## Troubleshooting + +### Common Issues + +| Issue | Solution | +| ----------------------- | ---------------------------------------------------------- | +| "OpenCode not found" | Run `caly-xano oc setup` to install configuration | +| "Agent not recognized" | Check agent name spelling, run `caly-xano oc setup --force` | +| "Permission denied" | Adjust permissions in `opencode.json` | +| Templates out of date | Run `caly-xano oc setup --force` to update | +| Native host not working | Re-run `caly-xano oc setup`, check registry (Windows) | +| Server won't start | Check if port is in use, try different port | + +### Checking Installation Status + +```bash +# Check what's installed +ls ~/.calycode/opencode/ + +# View configuration +cat ~/.calycode/opencode/opencode.json + +# List available agents +ls ~/.calycode/opencode/agents/ + +# List available commands +ls ~/.calycode/opencode/commands/ + +# List available skills +ls ~/.calycode/opencode/skills/ +``` + +### Logs + +Native host logs are written to `~/.calycode/logs/native-host.log`: + +```bash +# View logs (Unix) +tail -f ~/.calycode/logs/native-host.log + +# View logs (Windows PowerShell) +Get-Content -Wait $env:USERPROFILE\.calycode\logs\native-host.log +``` + +### Clearing Cache + +```bash +# Clear template cache and re-download +caly-xano oc setup --force +``` + +## Best Practices + +### 1. Recommended Workflow + +1. **Plan first** - Use `@xano-planner` to create an implementation plan +2. **Tables first** - Create database schemas before APIs +3. **Functions for reuse** - Extract common logic into functions +4. **APIs last** - Build endpoints that use tables and functions +5. **Tasks for automation** - Add scheduled jobs as needed + +### 2. Organize Your Prompts + +```bash +# Be specific about what you want +caly-xano oc run "@xano-table-designer Create a products table with: +- name (text, required, max 255) +- price (decimal, required, min 0) +- description (text, optional) +- category_id (foreign key to categories) +- created_at (timestamp, auto)" + +# Provide context +caly-xano oc run "@xano-api-writer Create a checkout API that: +- Uses the orders table we just created +- Validates cart items exist +- Calculates total with tax +- Returns order confirmation" +``` + +### 3. Use Skills for Complex Tasks + +For optimization or security-sensitive work, reference the appropriate skill: + +```bash +# Security review +caly-xano oc run "Use xano-security skill to audit this user registration endpoint" + +# Performance optimization +caly-xano oc run "Apply xano-query-performance to optimize this dashboard query" +``` + +## Resources + +- [OpenCode Documentation](https://opencode.ai/docs) +- [XanoScript Guide](/guides/xanoscript) +- [CalyCode CLI Reference](/commands) +- [GitHub Repository](https://github.com/calycode/xano-tools) +- [Discord Community](https://links.calycode.com/discord) diff --git a/docs/guides/patterns.md b/docs/guides/patterns.md index f66950fb..60908707 100644 --- a/docs/guides/patterns.md +++ b/docs/guides/patterns.md @@ -41,18 +41,18 @@ This guide provides recommendations and points to comprehensive resources. npm install -g @calycode/cli # Initialize for your Xano instance -xano init +caly-xano init # Follow the interactive prompts # Verify setup -xano context show +caly-xano context show ``` ### Version Control Workflow ```bash # Generate repository with XanoScript -xano generate repo \ +caly-xano generate repo \ --instance production \ --workspace main \ --branch live @@ -147,14 +147,14 @@ main (production) 1. **Export XanoScript** before merging: ```bash - xano generate xanoscript --branch feature/new-feature + caly-xano generate xanoscript --branch feature/new-feature ``` 2. **Review in Git** - Use standard PR workflows 3. **Run tests** before deployment: ```bash - xano test run -c ./tests/config.json --branch develop --ci + caly-xano test run -c ./tests/config.json --branch develop --ci ``` ## Architecture Patterns @@ -289,28 +289,28 @@ Found a useful pattern? Share it with the community: ```bash # Initialize CLI -xano init +caly-xano init # Generate repository -xano generate repo +caly-xano generate repo # Extract XanoScript -xano generate xanoscript +caly-xano generate xanoscript # Create registry -xano registry scaffold --output ./my-registry +caly-xano registry scaffold --output ./my-registry # Serve registry locally -xano serve registry --path ./my-registry +caly-xano serve registry --path ./my-registry # Install components -xano registry add component-name --registry +caly-xano registry add component-name --registry # Run tests -xano test run -c ./config.json --ci +caly-xano test run -c ./config.json --ci # Generate documentation -xano generate docs +caly-xano generate docs ``` ### Environment Variables diff --git a/docs/guides/registry-authoring.md b/docs/guides/registry-authoring.md index 7c07b6f1..39583dec 100644 --- a/docs/guides/registry-authoring.md +++ b/docs/guides/registry-authoring.md @@ -42,7 +42,7 @@ The Xano Tools registry system enables you to: ```bash # Create a new registry folder with sample components -xano registry scaffold --output ./my-registry +caly-xano registry scaffold --output ./my-registry ``` This creates: @@ -81,7 +81,7 @@ Edit `items/sample-function/definition.json`: ### 3. Serve Your Registry Locally ```bash -xano serve registry --path ./my-registry +caly-xano serve registry --path ./my-registry ``` Registry available at: `http://localhost:5500/registry/definitions` @@ -90,7 +90,7 @@ Registry available at: `http://localhost:5500/registry/definitions` ```bash # In another terminal, install to your Xano instance -xano registry add my-utils/string-helpers \ +caly-xano registry add my-utils/string-helpers \ --registry http://localhost:5500/registry/definitions \ --instance my-instance \ --workspace main \ @@ -331,7 +331,7 @@ For comprehensive XanoScript documentation, see: ### How Dependencies Work -When you install a component with `xano registry add`: +When you install a component with `caly-xano registry add`: 1. The CLI reads the component's `registryDependencies` array 2. All dependencies are resolved recursively @@ -406,10 +406,10 @@ Components track versions via metadata: ```bash # Terminal 1: Serve your registry -xano serve registry --path ./my-registry +caly-xano serve registry --path ./my-registry # Terminal 2: Test installation -xano registry add my-component \ +caly-xano registry add my-component \ --registry http://localhost:5500/registry/definitions \ --instance test-instance \ --workspace dev \ @@ -470,7 +470,7 @@ Package your registry for npm distribution: "name": "@your-org/xano-registry", "files": ["registry/**"], "scripts": { - "serve": "xano serve registry --path ./registry" + "serve": "caly-xano serve registry --path ./registry" } } ``` @@ -479,7 +479,7 @@ Package your registry for npm distribution: ```bash # Team members install from your registry -xano registry add auth/jwt-verify \ +caly-xano registry add auth/jwt-verify \ --registry https://registry.your-company.com/definitions ``` @@ -496,7 +496,7 @@ For organizations using private npm registries, you can leverage npm's scoped pa "private": true, "files": ["registry/**"], "scripts": { - "serve": "xano serve registry --path ./registry", + "serve": "caly-xano serve registry --path ./registry", "validate": "npx ajv validate -s https://calycode.com/schemas/registry/registry.json -d ./registry/registry.json" }, "publishConfig": { @@ -518,10 +518,10 @@ npm login --registry=https://npm.pkg.github.com --scope=@acme-corp npm install @acme-corp/xano-components # 4. Serve the registry locally from node_modules -xano serve registry --path ./node_modules/@acme-corp/xano-components/registry +caly-xano serve registry --path ./node_modules/@acme-corp/xano-components/registry # 5. Install components from the local registry -xano registry add auth/sso-integration \ +caly-xano registry add auth/sso-integration \ --registry http://localhost:5500/registry/definitions \ --instance production \ --workspace main diff --git a/docs/guides/scaffolding.md b/docs/guides/scaffolding.md index 2b89d452..b145e33c 100644 --- a/docs/guides/scaffolding.md +++ b/docs/guides/scaffolding.md @@ -35,16 +35,16 @@ This approach enables: ```bash # 1. Scaffold a new registry -xano registry scaffold --output ./my-components +caly-xano registry scaffold --output ./my-components # 2. Navigate to the scaffolded registry cd my-components # 3. Serve the registry locally -xano serve registry --path . +caly-xano serve registry --path . # 4. In another terminal, install to your Xano instance -xano registry add sample-function \ +caly-xano registry add sample-function \ --registry http://localhost:5500/registry/definitions \ --instance my-instance \ --workspace main \ @@ -56,7 +56,7 @@ xano registry add sample-function \ ### The Scaffold Command ```bash -xano registry scaffold --output [--instance ] +caly-xano registry scaffold --output [--instance ] ``` **Options:** @@ -232,7 +232,7 @@ For XanoScript syntax and examples, refer to: 1. **Install Xano VS Code Extension** - Best development experience 2. **Extract existing code** - Learn from your existing Xano functions: ```bash - xano generate xanoscript --instance prod --workspace main --branch live + caly-xano generate xanoscript --instance prod --workspace main --branch live ``` 3. **Study extracted files** - Understand XanoScript patterns 4. **Create new components** - Apply patterns to new components @@ -241,7 +241,7 @@ For XanoScript syntax and examples, refer to: ```bash # Extract XanoScript from existing project for reference -xano generate xanoscript \ +caly-xano generate xanoscript \ --instance my-instance \ --workspace main \ --branch live @@ -312,10 +312,10 @@ my-registry/ ```bash # Terminal 1: Serve registry -xano serve registry --path ./my-registry +caly-xano serve registry --path ./my-registry # Terminal 2: Install components -xano registry add auth/login \ +caly-xano registry add auth/login \ --registry http://localhost:5500/registry/definitions \ --instance dev-instance \ --workspace sandbox \ @@ -326,7 +326,7 @@ xano registry add auth/login \ ```bash # Install from hosted registry -xano registry add auth/login utils/string-helpers \ +caly-xano registry add auth/login utils/string-helpers \ --registry https://registry.mycompany.com/definitions \ --instance production \ --workspace main \ @@ -337,7 +337,7 @@ xano registry add auth/login utils/string-helpers \ ```bash # Space-separated list -xano registry add tables/user tables/session auth/login auth/register \ +caly-xano registry add tables/user tables/session auth/login auth/register \ --registry http://localhost:5500/registry/definitions ``` @@ -400,7 +400,7 @@ Bad: ```bash # Always test in a development branch first -xano registry add my-component \ +caly-xano registry add my-component \ --registry http://localhost:5500/registry/definitions \ --instance test \ --workspace dev \ diff --git a/docs/guides/testing.md b/docs/guides/testing.md index 9bbc0f04..efa99b37 100644 --- a/docs/guides/testing.md +++ b/docs/guides/testing.md @@ -33,16 +33,16 @@ The Caly Xano CLI provides a powerful API testing framework that: # test-config.json (see examples below) # 2. Run tests -xano test run -c ./test-config.json +caly-xano test run -c ./test-config.json # 3. Run tests with environment variables -xano test run -c ./test-config.json -e API_KEY=secret -e USER_EMAIL=test@example.com +caly-xano test run -c ./test-config.json -e API_KEY=secret -e USER_EMAIL=test@example.com # 4. Run in CI mode (exit code 1 on failure) -xano test run -c ./test-config.json --ci +caly-xano test run -c ./test-config.json --ci # 5. Run for all API groups -xano test run -c ./test-config.json --all --ci +caly-xano test run -c ./test-config.json --all --ci ``` ## Command Options @@ -398,7 +398,7 @@ When `customAsserts` is empty or not provided, these built-in assertions run: ```bash # Run tests and fail pipeline on errors -xano test run -c ./test-config.json --ci +caly-xano test run -c ./test-config.json --ci ``` ### GitHub Actions Example @@ -426,19 +426,19 @@ jobs: - name: Install Caly CLI run: npm install -g @calycode/cli - - name: Run API Tests - env: - XANO_TEST_EMAIL: ${{ secrets.TEST_EMAIL }} - XANO_TEST_PASSWORD: ${{ secrets.TEST_PASSWORD }} - XANO_TOKEN_PRODUCTION: ${{ secrets.XANO_TOKEN }} - run: | - xano test run \ - -c ./test-config.json \ - --instance production \ - --workspace main \ - --branch prod \ - --all \ - --ci + - name: Run API Tests + env: + XANO_TEST_EMAIL: ${{ secrets.TEST_EMAIL }} + XANO_TEST_PASSWORD: ${{ secrets.TEST_PASSWORD }} + XANO_TOKEN_PRODUCTION: ${{ secrets.XANO_TOKEN }} + run: | + caly-xano test run \ + -c ./test-config.json \ + --instance production \ + --workspace main \ + --branch prod \ + --all \ + --ci - name: Upload Test Results if: always() @@ -454,10 +454,10 @@ jobs: api-tests: stage: test image: node:20 - before_script: - - npm install -g @calycode/cli - script: - - xano test run -c ./test-config.json --all --ci + before_script: + - npm install -g @calycode/cli + script: + - caly-xano test run -c ./test-config.json --all --ci variables: XANO_TEST_EMAIL: ${TEST_EMAIL} XANO_TEST_PASSWORD: ${TEST_PASSWORD} @@ -561,13 +561,13 @@ tests/ ```bash # Development -xano test run -c ./tests/test-config.dev.js --branch dev +caly-xano test run -c ./tests/test-config.dev.js --branch dev # Staging -xano test run -c ./tests/test-config.staging.js --branch staging +caly-xano test run -c ./tests/test-config.staging.js --branch staging # Production (read-only tests) -xano test run -c ./tests/test-config.prod.js --branch prod --ci +caly-xano test run -c ./tests/test-config.prod.js --branch prod --ci ``` ## Test Results diff --git a/docs/guides/xanoscript.md b/docs/guides/xanoscript.md index b86836c6..c8cf9bc0 100644 --- a/docs/guides/xanoscript.md +++ b/docs/guides/xanoscript.md @@ -46,7 +46,7 @@ Extract XanoScript from your Xano workspace for version control: ```bash # Extract XanoScript from all supported entities -xano generate xanoscript \ +caly-xano generate xanoscript \ --instance production \ --workspace main \ --branch live @@ -60,7 +60,7 @@ Include XanoScript in your repository structure: ```bash # Generate complete repo with XanoScript -xano generate repo \ +caly-xano generate repo \ --instance production \ --workspace main \ --branch live @@ -88,7 +88,7 @@ Include XanoScript in reusable registry components: Deploy XanoScript-based components to your Xano instance: ```bash -xano registry add utils/jwt-helper \ +caly-xano registry add utils/jwt-helper \ --registry https://registry.example.com/definitions ``` @@ -121,10 +121,10 @@ Xano Tools can process the following XanoScript entity types: ```bash # Extract from current context -xano generate xanoscript +caly-xano generate xanoscript # Extract from specific instance/workspace/branch -xano generate xanoscript \ +caly-xano generate xanoscript \ --instance my-instance \ --workspace my-workspace \ --branch main @@ -165,7 +165,7 @@ Extracted files are organized by entity type: XanoScript is automatically included when generating a repository: ```bash -xano generate repo --instance production --workspace main --branch live +caly-xano generate repo --instance production --workspace main --branch live ``` ## Using XanoScript in Registries @@ -234,10 +234,10 @@ Components can include multiple XanoScript files: ### Recommended Setup 1. **Use the Xano VS Code Extension** - Best experience for XanoScript development -2. **Extract existing code** - Use `xano generate xanoscript` to get your current code +2. **Extract existing code** - Use `caly-xano generate xanoscript` to get your current code 3. **Develop in VS Code** - Edit XanoScript with syntax highlighting 4. **Package in registries** - Create reusable components -5. **Deploy via CLI** - Use `xano registry add` to install +5. **Deploy via CLI** - Use `caly-xano registry add` to install ### VS Code Extension @@ -256,7 +256,7 @@ XanoScript files are text-based and work well with Git: ```bash # Generate XanoScript for version control -xano generate xanoscript --instance prod --workspace main --branch live +caly-xano generate xanoscript --instance prod --workspace main --branch live # Commit changes git add . diff --git a/docs/xano.md b/docs/xano.md index 2197fc31..e76eb4c2 100644 --- a/docs/xano.md +++ b/docs/xano.md @@ -1,8 +1,8 @@ # @calycode/cli ```sh -caly-xano-cli v0.15.0 — Automate backups, docs, testing & version control for Xano +caly-xano-cli v0.16.0 — Automate backups, docs, testing & version control for Xano -Usage: xano [options] +Usage: caly-xano [options] Core: └─ init Initialize CLI with Xano instance config @@ -33,6 +33,9 @@ Backups: ├─ backup export Export workspace backup └─ backup restore Restore backup to workspace -Run 'xano --help' for detailed usage. +Other: + └─ oc skills install Install or reinstall Xano skills for AI agents. + +Run 'caly-xano --help' for detailed usage. https://github.com/calycode/xano-tools | https://links.calycode.com/discord ``` diff --git a/package.json b/package.json index 350dccbd..3c98341b 100644 --- a/package.json +++ b/package.json @@ -11,7 +11,8 @@ "build:docs:styles": "npx tailwindcss -i util-resources/tailwind-input.css -o util-resources/docs-template/styles.css --minify", "clean": "turbo run clean", "build:docs": "pnpm run build && tsx scripts/generate-caly-cli-docs.ts", - "xano": "pnpm --filter @calycode/cli run xano", + "caly-xano": "pnpm --filter @calycode/cli run caly-xano", + "xano": "node scripts/legacy-xano-command.mjs", "prepublishOnly": "pnpm run build", "serve-registry": "npx serve registry --listen 3030" }, @@ -50,4 +51,4 @@ "typescript": "^5.9.2" }, "packageManager": "pnpm@10.20.0" -} \ No newline at end of file +} diff --git a/packages/cli/README.md b/packages/cli/README.md index a8992582..e51b2622 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -22,7 +22,7 @@ The CLI package provides: ```bash npm install -g @calycode/cli ## pnpm install @calycode/cli -g -xano --help +caly-xano --help ``` ### NPX Usage @@ -51,32 +51,32 @@ Every command inherit context from: ```bash # Setup instance (interactive) -xano init +caly-xano init # Or non-interactive setup -xano init --name production --url https://x123.xano.io --token your-metadata-api-token +caly-xano init --name production --url https://x123.xano.io --token your-metadata-api-token # Generate OpenAPI specs -xano generate spec --all +caly-xano generate spec --all # Generate TypeScript client -xano generate codegen --generator typescript-fetch +caly-xano generate codegen --generator typescript-fetch # Serve documentation -xano serve spec +caly-xano serve spec ``` ### Multi-Environment Setup ```bash # Setup multiple instances -xano init --name production --url https://prod.my-instance.xano.io --token prod-token -xano init --name staging --url https://staging.my-instance.xano.io --token staging-token +caly-xano init --name production --url https://prod.my-instance.xano.io --token prod-token +caly-xano init --name staging --url https://staging.my-instance.xano.io --token staging-token -xano generate spec --group api +caly-xano generate spec --group api # You will be prompted to select all missing context information via prompts. -xano backup export +caly-xano backup export ``` ## Integration @@ -136,11 +136,11 @@ In order to actually use the CLI with proper git support it is advised to also d This allows users to override the output and as a result keep a proper git history. The flow is as follows: -1. Run the `xano init` command to configure your instance +1. Run the `caly-xano init` command to configure your instance 2. Make sure you have git installed on your machine 3. Run `git init` -4. Run a command e.g. `xano generate repo --output lib` and then commit these changes to your desired branch -5. Create new branch (possibly name similarly as on your Xano) and run the `xano generate repo --output lib` again. After a new commit and push you now have a fully git-enabled comparison of your two Xano branches. +4. Run a command e.g. `caly-xano generate repo --output lib` and then commit these changes to your desired branch +5. Create new branch (possibly name similarly as on your Xano) and run the `caly-xano generate repo --output lib` again. After a new commit and push you now have a fully git-enabled comparison of your two Xano branches. For a complete guide, see the [Git Workflow documentation](https://calycode.com/cli/docs/#/guides/git-workflow). diff --git a/packages/cli/package.json b/packages/cli/package.json index 86429469..b8e69e1a 100644 --- a/packages/cli/package.json +++ b/packages/cli/package.json @@ -20,7 +20,7 @@ "developer-tools" ], "bin": { - "xano": "dist/index.cjs" + "caly-xano": "dist/index.cjs" }, "main": "dist/index.cjs", "type": "module", @@ -65,7 +65,7 @@ "bundle:ncc": "pnpm ncc build dist/index.cjs -o dist/cli.cjs && shx cp README.md LICENSE dist/cli.cjs/", "bundle:sea": "tsx build-sea.ts", "bundle": "pnpm bundle:ncc && pnpm bundle:sea", - "xano": "node dist/index.cjs" + "caly-xano": "node dist/index.cjs" }, "pkg": { "name": "@calycode-cli-installer", @@ -85,4 +85,4 @@ "opencode-ai": "^1.1.35", "posthog-node": "^5.9.2" } -} \ No newline at end of file +} diff --git a/packages/cli/scripts/README.md b/packages/cli/scripts/README.md index e1c5d6b6..5da1be34 100644 --- a/packages/cli/scripts/README.md +++ b/packages/cli/scripts/README.md @@ -115,7 +115,7 @@ These URLs should be configured as a GitHub Pages site or CDN pointing to the `s ## Troubleshooting -### "xano command not found" after installation +### "caly-xano command not found" after installation The PATH may not have been updated in your current terminal session. @@ -138,4 +138,4 @@ The PATH may not have been updated in your current terminal session. 3. Check logs at `~/.calycode/logs/native-host.log` -4. Re-run: `xano opencode init` +4. Re-run: `caly-xano opencode init` diff --git a/packages/cli/scripts/dev/install-unix.sh b/packages/cli/scripts/dev/install-unix.sh index fc3aba64..1ec4a152 100644 --- a/packages/cli/scripts/dev/install-unix.sh +++ b/packages/cli/scripts/dev/install-unix.sh @@ -3,7 +3,7 @@ # CalyCode Native Host Installer (Development) # ============================================================================ # This script is for developers working on the CLI itself. -# It assumes the CLI is already available via 'xano' command (linked or built). +# It assumes the CLI is already available via 'caly-xano' command (linked or built). # # For end-users, use the production installer instead: # curl -fsSL https://get.calycode.com/install.sh | bash @@ -103,13 +103,13 @@ main() { install_node fi - # Check if xano command exists (assumes dev environment is set up) - if ! command -v xano >/dev/null 2>&1; then - fatal "The 'xano' command is not available. Please ensure you have linked or built the CLI." + # Check if caly-xano command exists (assumes dev environment is set up) + if ! command -v caly-xano >/dev/null 2>&1; then + fatal "The 'caly-xano' command is not available. Please ensure you have linked or built the CLI." fi log "Initializing Native Host..." - xano opencode init + caly-xano opencode init echo "" log "Setup complete! You can reload the Chrome extension now." diff --git a/packages/cli/scripts/dev/install-win.bat b/packages/cli/scripts/dev/install-win.bat index 5a2c02cd..1eb8b5f6 100644 --- a/packages/cli/scripts/dev/install-win.bat +++ b/packages/cli/scripts/dev/install-win.bat @@ -5,7 +5,7 @@ REM ============================================================================ REM CalyCode Native Host Installer (Development) REM ============================================================================ REM This script is for developers working on the CLI itself. -REM It assumes the CLI is already available via 'xano' command (linked or built). +REM It assumes the CLI is already available via 'caly-xano' command (linked or built). REM REM For end-users, use the production installer instead: REM Run install.bat from the installer/ directory, or: @@ -69,10 +69,10 @@ if exist "C:\Program Files\nodejs\node.exe" ( :SetupNativeHost echo. -REM Check if xano command exists (assumes dev environment is set up) -where xano >nul 2>nul +REM Check if caly-xano command exists (assumes dev environment is set up) +where caly-xano >nul 2>nul if %ERRORLEVEL% NEQ 0 ( - echo [ERROR] The 'xano' command is not available. + echo [ERROR] The 'caly-xano' command is not available. echo Please ensure you have linked or built the CLI. echo. echo Try running: npm link @@ -82,7 +82,7 @@ if %ERRORLEVEL% NEQ 0 ( ) echo [INFO] Initializing Native Host... -call xano opencode init +call caly-xano opencode init if %ERRORLEVEL% NEQ 0 ( echo [ERROR] Failed to initialize native host. pause diff --git a/packages/cli/scripts/installer/install.ps1 b/packages/cli/scripts/installer/install.ps1 index d2acbe36..53664c51 100644 --- a/packages/cli/scripts/installer/install.ps1 +++ b/packages/cli/scripts/installer/install.ps1 @@ -229,12 +229,12 @@ function Install-CalyCodeCLI { # Verify installation Update-PathEnvironment - if (Get-Command xano -ErrorAction SilentlyContinue) { - $cliVersion = (xano --version 2>$null) -replace '\n', '' + if (Get-Command caly-xano -ErrorAction SilentlyContinue) { + $cliVersion = (caly-xano --version 2>$null) -replace '\n', '' Write-Log "CLI version: $cliVersion" "INFO" } else { - Write-Log "The 'xano' command is not in PATH. You may need to restart your terminal." "WARN" + Write-Log "The 'caly-xano' command is not in PATH. You may need to restart your terminal." "WARN" } return $true @@ -254,14 +254,14 @@ function Initialize-NativeHost { Write-Header "Configuring Chrome Native Messaging Host..." - if (-not (Get-Command xano -ErrorAction SilentlyContinue)) { - Write-Log "Cannot configure native host: 'xano' command not found in PATH" "WARN" - Write-Log "Please restart your terminal and run: xano opencode init" "WARN" + if (-not (Get-Command caly-xano -ErrorAction SilentlyContinue)) { + Write-Log "Cannot configure native host: 'caly-xano' command not found in PATH" "WARN" + Write-Log "Please restart your terminal and run: caly-xano opencode init" "WARN" return $false } try { - xano opencode init + caly-xano opencode init return $true } catch { @@ -275,7 +275,7 @@ function Invoke-Uninstall { Write-Header "Uninstalling CalyCode CLI..." # Remove npm package - if (Get-Command xano -ErrorAction SilentlyContinue) { + if (Get-Command caly-xano -ErrorAction SilentlyContinue) { Write-Log "Removing $PackageName package..." "INFO" npm uninstall -g $PackageName 2>$null } @@ -325,9 +325,9 @@ function Write-Completion { Write-Host "============================================" -ForegroundColor Green Write-Host "" Write-Host " Getting Started:" -ForegroundColor Cyan - Write-Host " xano --help Show available commands" - Write-Host " xano opencode init Reconfigure Chrome extension" - Write-Host " xano opencode serve Start local AI server" + Write-Host " caly-xano --help Show available commands" + Write-Host " caly-xano opencode init Reconfigure Chrome extension" + Write-Host " caly-xano opencode serve Start local AI server" Write-Host "" Write-Host " Documentation:" -ForegroundColor Cyan Write-Host " https://calycode.com/docs" diff --git a/packages/cli/scripts/installer/install.sh b/packages/cli/scripts/installer/install.sh index 8545a704..dd6bbf52 100644 --- a/packages/cli/scripts/installer/install.sh +++ b/packages/cli/scripts/installer/install.sh @@ -97,7 +97,7 @@ uninstall() { header "Uninstalling CalyCode CLI..." # Remove npm package - if command -v xano >/dev/null 2>&1; then + if command -v caly-xano >/dev/null 2>&1; then log "Removing @calycode/cli package..." npm uninstall -g @calycode/cli 2>/dev/null || sudo npm uninstall -g @calycode/cli 2>/dev/null || true fi @@ -312,10 +312,10 @@ install_cli() { fi # Verify installation - if ! command -v xano >/dev/null 2>&1; then - warn "The 'xano' command is not in PATH. You may need to restart your terminal." + if ! command -v caly-xano >/dev/null 2>&1; then + warn "The 'caly-xano' command is not in PATH. You may need to restart your terminal." else - log "CLI version: $(xano --version 2>/dev/null || echo 'unknown')" + log "CLI version: $(caly-xano --version 2>/dev/null || echo 'unknown')" fi } @@ -328,13 +328,13 @@ configure_native_host() { header "Configuring Chrome Native Messaging Host..." - if ! command -v xano >/dev/null 2>&1; then - warn "Cannot configure native host: 'xano' command not found in PATH" - warn "Please restart your terminal and run: xano opencode init" + if ! command -v caly-xano >/dev/null 2>&1; then + warn "Cannot configure native host: 'caly-xano' command not found in PATH" + warn "Please restart your terminal and run: caly-xano opencode init" return 1 fi - xano opencode init + caly-xano opencode init } # Print completion message @@ -345,9 +345,9 @@ print_completion() { echo -e "${GREEN}${BOLD}============================================${NC}" echo "" echo -e " ${CYAN}Getting Started:${NC}" - echo " xano --help Show available commands" - echo " xano opencode init Reconfigure Chrome extension" - echo " xano opencode serve Start local AI server" + echo " caly-xano --help Show available commands" + echo " caly-xano opencode init Reconfigure Chrome extension" + echo " caly-xano opencode serve Start local AI server" echo "" echo -e " ${CYAN}Documentation:${NC}" echo " https://calycode.com/docs" diff --git a/packages/cli/src/commands/opencode/index.ts b/packages/cli/src/commands/opencode/index.ts index c51ee6ba..c89dbf90 100644 --- a/packages/cli/src/commands/opencode/index.ts +++ b/packages/cli/src/commands/opencode/index.ts @@ -73,7 +73,7 @@ async function registerOpencodeCommands(program) { if (!status.installed) { log.info( - 'No templates installed. Run "xano opencode templates install" to install.', + 'No templates installed. Run "caly-xano opencode templates install" to install.', ); return; } @@ -131,7 +131,7 @@ async function registerOpencodeCommands(program) { const status = getSkillsInstallStatus(); if (!status.installed) { - log.info('No skills installed. Run "xano opencode skills install" to install.'); + log.info('No skills installed. Run "caly-xano opencode skills install" to install.'); return; } @@ -201,7 +201,7 @@ async function registerOpencodeCommands(program) { // A safer way for a "passthrough" is often to inspect process.argv directly, // but let's try to trust the explicit args first or just grab the raw rest. - // Actually, for a pure proxy where we want "xano opencode foo --bar", + // Actually, for a pure proxy where we want "caly-xano opencode foo --bar", // "foo" becomes an arg, "--bar" might be parsed as an option if not careful. // Let's filter process.argv to find everything after "opencode" or "oc". @@ -219,7 +219,7 @@ async function registerOpencodeCommands(program) { // Filter out our own known subcommands if they were accidentally matched? // No, if we are here, it's because it wasn't init/serve/native-host (mostly). - // BUT 'run' is default, so 'xano opencode' (no args) also lands here. + // BUT 'run' is default, so 'caly-xano opencode' (no args) also lands here. await proxyOpencode(passThroughArgs); }); diff --git a/packages/cli/src/index-bundled.ts b/packages/cli/src/index-bundled.ts index 8dbabc78..44611895 100644 --- a/packages/cli/src/index-bundled.ts +++ b/packages/cli/src/index-bundled.ts @@ -3,6 +3,7 @@ import { isSea } from 'node:sea'; import { program } from './program'; import { setupOpencode, startNativeHost } from './commands/opencode/implementation'; import { HOST_APP_INFO } from './utils/host-constants'; +import { exitIfLegacyXanoInvocation } from './utils/legacy-command-guard'; /** * Escape a string for safe use in PowerShell. @@ -33,6 +34,7 @@ function escapeAppleScript(str: string): string { (async () => { const isBundled = isSea(); const args = process.argv; + exitIfLegacyXanoInvocation(args); // Check if we are being called as the Native Host // This handles both direct chrome-extension:// invocations (Linux/Mac) diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts index 978f3b50..aff7363a 100644 --- a/packages/cli/src/index.ts +++ b/packages/cli/src/index.ts @@ -1,10 +1,12 @@ import { program } from './program'; import { startNativeHost } from './commands/opencode/implementation'; +import { exitIfLegacyXanoInvocation } from './utils/legacy-command-guard'; // Check if we are being called as the Native Host // This happens when the argument list includes 'opencode' and 'native-host' // Bypassing Commander here ensures a cleaner stdout for the binary protocol const args = process.argv; +exitIfLegacyXanoInvocation(args); if (args.includes('opencode') && args.includes('native-host')) { startNativeHost(); } else { diff --git a/packages/cli/src/program.ts b/packages/cli/src/program.ts index 86665fe2..47e0589a 100644 --- a/packages/cli/src/program.ts +++ b/packages/cli/src/program.ts @@ -60,7 +60,7 @@ program.hook('postAction', (thisCommand, actionCommand) => { }); program - .name('xano') + .name('caly-xano') .version(version, '-v, --version', 'output the version number') .usage(' [options]') .description( diff --git a/packages/cli/src/utils/commands/main-program-utils.ts b/packages/cli/src/utils/commands/main-program-utils.ts index 2c291435..4fd248f1 100644 --- a/packages/cli/src/utils/commands/main-program-utils.ts +++ b/packages/cli/src/utils/commands/main-program-utils.ts @@ -29,15 +29,17 @@ function getFullCommandPath(cmd) { path.push(current.name()); current = current.parent; } - // Remove 'xano' or '' from the path if present + // Remove root command names from the path if present return path .reverse() - .filter((seg) => seg && seg !== 'xano') + .filter((seg) => seg && seg !== 'xano' && seg !== 'caly-xano') .join(' '); } function collectVisibleLeafCommands(cmd, parentPath = [], parentHiddenFromRoot = false) { - const path = [...parentPath, cmd.name()].filter((segment) => segment !== 'xano'); + const path = [...parentPath, cmd.name()].filter( + (segment) => segment !== 'xano' && segment !== 'caly-xano', + ); let results = []; // Track if this command or any ancestor is hidden from root help @@ -141,7 +143,7 @@ function customFormatHelp(cmd, helper) { } // 6. Footer - output.push(font.color.gray("Run 'xano --help' for detailed usage.")); + output.push(font.color.gray("Run 'caly-xano --help' for detailed usage.")); output.push( font.color.gray('https://github.com/calycode/xano-tools | https://links.calycode.com/discord'), ); @@ -231,7 +233,7 @@ function customFormatHelpForRoot(cmd) { output.push(cmd.description()); } output.push(''); - output.push(font.color.gray('Usage: xano [options]')); + output.push(font.color.gray('Usage: caly-xano [options]')); output.push(''); // 7. Command Groups with tree structure @@ -258,7 +260,7 @@ function customFormatHelpForRoot(cmd) { } // Footer - output.push(font.color.gray("Run 'xano --help' for detailed usage.")); + output.push(font.color.gray("Run 'caly-xano --help' for detailed usage.")); output.push( font.color.gray('https://github.com/calycode/xano-tools | https://links.calycode.com/discord'), ); diff --git a/packages/cli/src/utils/legacy-command-guard.ts b/packages/cli/src/utils/legacy-command-guard.ts new file mode 100644 index 00000000..dffdad94 --- /dev/null +++ b/packages/cli/src/utils/legacy-command-guard.ts @@ -0,0 +1,25 @@ +import path from 'node:path'; + +const LEGACY_XANO_BINARY_NAMES = new Set(['xano', 'xano.cmd', 'xano.ps1', 'xano.exe']); + +function isNativeHostInvocation(args: string[]): boolean { + return args.includes('opencode') && args.includes('native-host'); +} + +function exitIfLegacyXanoInvocation(args: string[]) { + if (isNativeHostInvocation(args)) { + return; + } + + const invokedBinary = path.basename(args[1] ?? '').toLowerCase(); + if (!LEGACY_XANO_BINARY_NAMES.has(invokedBinary)) { + return; + } + + console.error('The `xano` command has moved to Xano\'s official CLI.'); + console.error('Use `caly-xano` for CalyCode CLI commands.'); + console.error('Need the official `xano` command? Install Xano\'s official CLI.'); + process.exit(1); +} + +export { exitIfLegacyXanoInvocation }; diff --git a/scripts/generate-caly-cli-docs.ts b/scripts/generate-caly-cli-docs.ts index 6e9c26e5..e8a4927e 100644 --- a/scripts/generate-caly-cli-docs.ts +++ b/scripts/generate-caly-cli-docs.ts @@ -57,11 +57,11 @@ function writeDocForCommand(cmd: any, docPath: string, nameParts: string[]) { description && `>[!NOTE|label:Description]\n> #### ${description}\n`, '', '```term', - `$ xano ${name} [options]`, + `$ caly-xano ${name} [options]`, '```', optionsContent, `\n### ${name} --help`, - `\`\`\`term\n$ xano ${name} --help`, + `\`\`\`term\n$ caly-xano ${name} --help`, help.trim(), '```', ] @@ -91,7 +91,7 @@ function generateCliDocs() { console.log('Generated main help. \n'); // 3. Recursively generate docs and sidebar - const sidebarLines = ['- [xano - the core command](xano.md)', '- **Commands**']; + const sidebarLines = ['- [caly-xano - the core command](xano.md)', '- **Commands**']; program.commands.forEach((cmd) => walkCommands(cmd, [], sidebarLines)); const finalSidebar = [ ...sidebarLines, diff --git a/scripts/legacy-xano-command.mjs b/scripts/legacy-xano-command.mjs new file mode 100644 index 00000000..a6fe8c5a --- /dev/null +++ b/scripts/legacy-xano-command.mjs @@ -0,0 +1,4 @@ +console.error('The `xano` command is no longer provided by @calycode/cli.'); +console.error('Use `caly-xano` for CalyCode CLI commands.'); +console.error('If you want the official `xano` command, install Xano\'s official CLI.'); +process.exit(1); From d10df86b94901fd8fac79f958f5ce964018046f2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mih=C3=A1ly=20T=C3=B3th?= Date: Fri, 10 Apr 2026 09:32:41 +0200 Subject: [PATCH 2/5] chore: improve skill installation --- .changeset/nasty-facts-hammer.md | 5 +++++ packages/xano-skills/README.md | 2 +- packages/xano-skills/package.json | 9 ++++++--- 3 files changed, 12 insertions(+), 4 deletions(-) create mode 100644 .changeset/nasty-facts-hammer.md diff --git a/.changeset/nasty-facts-hammer.md b/.changeset/nasty-facts-hammer.md new file mode 100644 index 00000000..4e05c778 --- /dev/null +++ b/.changeset/nasty-facts-hammer.md @@ -0,0 +1,5 @@ +--- +"@calycode/xano-skills": patch +--- + +chore: improve installability diff --git a/packages/xano-skills/README.md b/packages/xano-skills/README.md index 6a16c47b..763cd45e 100644 --- a/packages/xano-skills/README.md +++ b/packages/xano-skills/README.md @@ -7,7 +7,7 @@ Agent skills for Xano backend development. This collection provides procedural k ### Via skills.sh CLI ```bash -npx skills add calycode/xano-tools +npx skills add calycode/xano-tools/packages/xano-skills ``` ### Via CalyCode CLI diff --git a/packages/xano-skills/package.json b/packages/xano-skills/package.json index a721793d..59c56d8d 100644 --- a/packages/xano-skills/package.json +++ b/packages/xano-skills/package.json @@ -1,6 +1,6 @@ { "name": "@calycode/xano-skills", - "version": "0.1.0", + "version": "0.2.1", "description": "Agent skills for Xano backend development - database optimization, security patterns, query performance, and best practices. Use with skills.sh or OpenCode.", "license": "MIT", "author": "CalyCode", @@ -9,7 +9,7 @@ "url": "https://github.com/calycode/xano-tools.git", "directory": "packages/xano-skills" }, - "homepage": "https://skills.sh/calycode/xano-tools", + "homepage": "https://github.com/calycode/xano-tools/tree/main/packages/xano-skills", "bugs": { "url": "https://github.com/calycode/xano-tools/issues" }, @@ -30,7 +30,10 @@ "AGENTS.md", "README.md" ], + "scripts": { + "install-xano-skills": "npx skills add calycode/xano-tools/packages/xano-skills --yes" + }, "publishConfig": { "access": "public" } -} +} \ No newline at end of file From 7c26d1e627748d2cdc27fdaa6590ac18f892b9ec Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mih=C3=A1ly=20T=C3=B3th?= Date: Fri, 10 Apr 2026 09:37:49 +0200 Subject: [PATCH 3/5] chore: adjust default models for opencode config templates --- docs/guides/opencode-setup.md | 4 ++-- .../opencode-templates/agents/api-designer.md | 2 +- .../opencode-templates/agents/debug-helper.md | 2 +- .../agents/xano-addon-writer.md | 2 +- .../agents/xano-ai-builder.md | 18 +----------------- .../agents/xano-api-writer.md | 2 +- .../agents/xano-function-writer.md | 2 +- .../opencode-templates/agents/xano-planner.md | 2 +- .../agents/xano-table-designer.md | 2 +- .../agents/xano-task-writer.md | 2 +- packages/opencode-templates/opencode.json | 4 ++-- .../docs-template/guides/opencode-setup.md | 4 ++-- 12 files changed, 15 insertions(+), 31 deletions(-) diff --git a/docs/guides/opencode-setup.md b/docs/guides/opencode-setup.md index 56f3579c..76520fa4 100644 --- a/docs/guides/opencode-setup.md +++ b/docs/guides/opencode-setup.md @@ -259,8 +259,8 @@ The main OpenCode configuration at `~/.calycode/opencode/opencode.json`: ```json { "$schema": "https://opencode.ai/config.json", - "model": "anthropic/claude-sonnet-4-20250514", - "small_model": "anthropic/claude-haiku-4-20250514", + "model": "github-copilot/claude-sonnet-4.5", + "small_model": "github-copilot/claude-haiku-4.5", "autoupdate": true, "instructions": ["~/.config/opencode/AGENTS.md"], "permission": { diff --git a/packages/opencode-templates/agents/api-designer.md b/packages/opencode-templates/agents/api-designer.md index 13345c5d..170754f8 100644 --- a/packages/opencode-templates/agents/api-designer.md +++ b/packages/opencode-templates/agents/api-designer.md @@ -1,7 +1,7 @@ --- description: Specialist in RESTful API design, endpoint architecture, and integration patterns. Helps design clean, scalable APIs. mode: subagent -model: anthropic/claude-sonnet-4-20250514 +model: github-copilot/claude-sonnet-4.5 temperature: 0.3 tools: read: true diff --git a/packages/opencode-templates/agents/debug-helper.md b/packages/opencode-templates/agents/debug-helper.md index b3827303..6716ec32 100644 --- a/packages/opencode-templates/agents/debug-helper.md +++ b/packages/opencode-templates/agents/debug-helper.md @@ -1,7 +1,7 @@ --- description: Helps troubleshoot issues, analyze errors, and debug problems in Xano backends and related code. mode: subagent -model: anthropic/claude-sonnet-4-20250514 +model: github-copilot/claude-sonnet-4.5 temperature: 0.1 tools: read: true diff --git a/packages/opencode-templates/agents/xano-addon-writer.md b/packages/opencode-templates/agents/xano-addon-writer.md index 52601a7b..4adfa3c6 100644 --- a/packages/opencode-templates/agents/xano-addon-writer.md +++ b/packages/opencode-templates/agents/xano-addon-writer.md @@ -1,7 +1,7 @@ --- description: Write XanoScript addons for fetching related data efficiently. Addons solve N+1 query problems by batching related data fetches. mode: subagent -model: anthropic/claude-sonnet-4-20250514 +model: github-copilot/claude-sonnet-4.5 temperature: 0.1 tools: read: true diff --git a/packages/opencode-templates/agents/xano-ai-builder.md b/packages/opencode-templates/agents/xano-ai-builder.md index 95e62e07..7e9f8d98 100644 --- a/packages/opencode-templates/agents/xano-ai-builder.md +++ b/packages/opencode-templates/agents/xano-ai-builder.md @@ -1,7 +1,7 @@ --- description: Build XanoScript AI agents, MCP servers, and tools for AI-powered automation and intelligent features. mode: subagent -model: anthropic/claude-sonnet-4-20250514 +model: github-copilot/claude-sonnet-4.5 temperature: 0.1 tools: read: true @@ -47,7 +47,6 @@ agent "Agent Display Name" { | Xano Free | `xano-free` | None required | | Google Gemini | `google-genai` | `{{ $env.gemini_key }}` | | OpenAI | `openai` | `{{ $env.openai_key }}` | -| Anthropic | `anthropic` | `{{ $env.anthropic_key }}` | ## Provider Configuration @@ -108,21 +107,6 @@ llm = { | `reasoning_effort` | `"low"`, `"medium"`, `"high"` for reasoning models | | `baseURL` | Custom endpoint (Groq, Mistral, OpenRouter) | -### Anthropic Claude - -```xanoscript -llm = { - type: "anthropic" - system_prompt: "You are a thoughtful assistant." - prompt: "{{ $args.task_description }}" - max_steps: 8 - api_key: "{{ $env.anthropic_key }}" - model: "claude-sonnet-4-5-20250929" - temperature: 0.3 - send_reasoning: true -} -``` - | Parameter | Description | | ---------------- | ----------------------------------- | | `send_reasoning` | Include thinking blocks in response | diff --git a/packages/opencode-templates/agents/xano-api-writer.md b/packages/opencode-templates/agents/xano-api-writer.md index 531ffd4b..36ae9a75 100644 --- a/packages/opencode-templates/agents/xano-api-writer.md +++ b/packages/opencode-templates/agents/xano-api-writer.md @@ -1,7 +1,7 @@ --- description: Write XanoScript API queries (REST endpoints) with authentication, validation, database operations, and proper response handling. mode: subagent -model: anthropic/claude-sonnet-4-20250514 +model: github-copilot/claude-sonnet-4.5 temperature: 0.1 tools: read: true diff --git a/packages/opencode-templates/agents/xano-function-writer.md b/packages/opencode-templates/agents/xano-function-writer.md index e6174686..720bb412 100644 --- a/packages/opencode-templates/agents/xano-function-writer.md +++ b/packages/opencode-templates/agents/xano-function-writer.md @@ -1,7 +1,7 @@ --- description: Write reusable XanoScript functions with inputs, business logic, and responses. Functions encapsulate complex operations for reuse. mode: subagent -model: anthropic/claude-sonnet-4-20250514 +model: github-copilot/claude-sonnet-4.5 temperature: 0.1 tools: read: true diff --git a/packages/opencode-templates/agents/xano-planner.md b/packages/opencode-templates/agents/xano-planner.md index eb2e8b9c..97a8d8fe 100644 --- a/packages/opencode-templates/agents/xano-planner.md +++ b/packages/opencode-templates/agents/xano-planner.md @@ -1,7 +1,7 @@ --- description: Plan and orchestrate XanoScript development across APIs, functions, tables, tasks, and AI features. Creates implementation roadmaps. mode: subagent -model: anthropic/claude-sonnet-4-20250514 +model: github-copilot/claude-sonnet-4.5 temperature: 0.2 tools: read: true diff --git a/packages/opencode-templates/agents/xano-table-designer.md b/packages/opencode-templates/agents/xano-table-designer.md index 29c52c87..aaf18d49 100644 --- a/packages/opencode-templates/agents/xano-table-designer.md +++ b/packages/opencode-templates/agents/xano-table-designer.md @@ -1,7 +1,7 @@ --- description: Design XanoScript database tables with schemas, field types, relationships, and indexes. Tables define your data model. mode: subagent -model: anthropic/claude-sonnet-4-20250514 +model: github-copilot/claude-sonnet-4.5 temperature: 0.1 tools: read: true diff --git a/packages/opencode-templates/agents/xano-task-writer.md b/packages/opencode-templates/agents/xano-task-writer.md index f77d53c4..0f19fc11 100644 --- a/packages/opencode-templates/agents/xano-task-writer.md +++ b/packages/opencode-templates/agents/xano-task-writer.md @@ -1,7 +1,7 @@ --- description: Write XanoScript scheduled tasks for automated jobs like data cleanup, reports, notifications, and background processing. mode: subagent -model: anthropic/claude-sonnet-4-20250514 +model: github-copilot/claude-sonnet-4.5 temperature: 0.1 tools: read: true diff --git a/packages/opencode-templates/opencode.json b/packages/opencode-templates/opencode.json index d9a9f229..43983f91 100644 --- a/packages/opencode-templates/opencode.json +++ b/packages/opencode-templates/opencode.json @@ -1,7 +1,7 @@ { "$schema": "https://opencode.ai/config.json", - "model": "anthropic/claude-sonnet-4-20250514", - "small_model": "anthropic/claude-haiku-4-20250514", + "model": "github-copilot/claude-sonnet-4.5", + "small_model": "github-copilot/claude-haiku-4.5", "autoupdate": true, "instructions": [ "~/.config/opencode/AGENTS.md" diff --git a/util-resources/docs-template/guides/opencode-setup.md b/util-resources/docs-template/guides/opencode-setup.md index cb5a6df1..8cbb7d1e 100644 --- a/util-resources/docs-template/guides/opencode-setup.md +++ b/util-resources/docs-template/guides/opencode-setup.md @@ -257,8 +257,8 @@ The main OpenCode configuration at `~/.calycode/opencode/opencode.json`: ```json { "$schema": "https://opencode.ai/config.json", - "model": "anthropic/claude-sonnet-4-20250514", - "small_model": "anthropic/claude-haiku-4-20250514", + "model": "github-copilot/claude-sonnet-4.5", + "small_model": "github-copilot/claude-haiku-4.5", "autoupdate": true, "instructions": ["~/.config/opencode/AGENTS.md"], "permission": { From 24888afbd8c5b64851ba3397d850aba08b4d7334 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mih=C3=A1ly=20T=C3=B3th?= Date: Fri, 10 Apr 2026 09:57:17 +0200 Subject: [PATCH 4/5] doc: update the guide templates to use correct commands --- .../docs-template/guides/git-workflow.md | 32 +++++----- .../docs-template/guides/opencode-setup.md | 62 +++++++++---------- .../docs-template/guides/patterns.md | 26 ++++---- .../guides/registry-authoring.md | 38 ++++++------ .../docs-template/guides/scaffolding.md | 22 +++---- .../docs-template/guides/testing.md | 20 +++--- .../docs-template/guides/xanoscript.md | 18 +++--- 7 files changed, 109 insertions(+), 109 deletions(-) diff --git a/util-resources/docs-template/guides/git-workflow.md b/util-resources/docs-template/guides/git-workflow.md index 369e4897..65b0b202 100644 --- a/util-resources/docs-template/guides/git-workflow.md +++ b/util-resources/docs-template/guides/git-workflow.md @@ -30,7 +30,7 @@ Xano Tools enables Git-based version control for your Xano backend by: npm install -g @calycode/cli # Initialize with your Xano instance -xano init +caly-xano init # Follow prompts to configure: # - Instance name @@ -43,7 +43,7 @@ xano init ```bash # Generate complete repository structure -xano generate repo \ +caly-xano generate repo \ --instance production \ --workspace main \ --branch live @@ -68,7 +68,7 @@ git push -u origin main ### The `generate repo` Command ```bash -xano generate repo [options] +caly-xano generate repo [options] ``` **Options:** @@ -107,7 +107,7 @@ project/ For just XanoScript (lighter weight): ```bash -xano generate xanoscript \ +caly-xano generate xanoscript \ --instance production \ --workspace main \ --branch live @@ -151,7 +151,7 @@ git checkout -b feature/new-api # (Use Calycode Extension for branch management) # Export changes -xano generate xanoscript --branch dev +caly-xano generate xanoscript --branch dev # Commit git add . @@ -167,7 +167,7 @@ git commit -m "Add new API endpoints" git pull origin develop # Check for updates from Xano -xano generate xanoscript --branch develop +caly-xano generate xanoscript --branch develop # Review changes git status @@ -178,7 +178,7 @@ git diff ```bash # Export your changes -xano generate repo --branch develop +caly-xano generate repo --branch develop # Review what changed git status @@ -200,13 +200,13 @@ git push origin feature/user-profile ```bash # Run tests -xano test run -c ./tests/config.json --branch develop --ci +caly-xano test run -c ./tests/config.json --branch develop --ci # Generate fresh docs -xano generate docs +caly-xano generate docs # Final export -xano generate repo --branch develop +caly-xano generate repo --branch develop # Commit any doc changes git add . @@ -244,7 +244,7 @@ jobs: env: XANO_TOKEN_PRODUCTION: ${{ secrets.XANO_TOKEN }} run: | - xano generate repo \ + caly-xano generate repo \ --instance production \ --workspace main \ --branch live \ @@ -296,7 +296,7 @@ jobs: XANO_TEST_EMAIL: ${{ secrets.TEST_EMAIL }} XANO_TEST_PASSWORD: ${{ secrets.TEST_PASSWORD }} run: | - xano test run \ + caly-xano test run \ -c ./tests/config.json \ --instance staging \ --workspace main \ @@ -331,7 +331,7 @@ jobs: - name: Generate Documentation env: XANO_TOKEN_PRODUCTION: ${{ secrets.XANO_TOKEN }} - run: xano generate docs + run: caly-xano generate docs - name: Deploy to GitHub Pages uses: peaceiris/actions-gh-pages@v3 @@ -425,7 +425,7 @@ XANO_TOKEN_STAGING=your-staging-token Before merging: - [ ] XanoScript exported and committed -- [ ] Tests pass (`xano test run --ci`) +- [ ] Tests pass (`caly-xano test run --ci`) - [ ] Documentation updated - [ ] No secrets in code - [ ] Follows naming conventions @@ -437,7 +437,7 @@ Before merging: | Issue | Solution | | ----------------------- | --------------------------------------- | -| "Instance not found" | Run `xano init` to configure | +| "Instance not found" | Run `caly-xano init` to configure | | "Authentication failed" | Check `XANO_TOKEN_*` env vars | | Merge conflicts in JSON | Regenerate from Xano, resolve manually | | Missing XanoScript | Ensure Xano 2.0+ for XanoScript support | @@ -449,7 +449,7 @@ Before merging: git checkout -- . # Fresh export from Xano -xano generate repo --fetch +caly-xano generate repo --fetch # Review and commit git add . diff --git a/util-resources/docs-template/guides/opencode-setup.md b/util-resources/docs-template/guides/opencode-setup.md index 8cbb7d1e..90f8d56c 100644 --- a/util-resources/docs-template/guides/opencode-setup.md +++ b/util-resources/docs-template/guides/opencode-setup.md @@ -33,21 +33,21 @@ The CalyCode CLI integrates with [OpenCode](https://opencode.ai), an open-source npm install -g @calycode/cli # 2. Set up OpenCode with agents, commands, and skills -xano oc setup +caly-xano oc setup # 3. Run OpenCode interactively -xano oc run +caly-xano oc run # 4. Or run with a specific agent -xano oc run "@xano-planner Plan a user authentication system" +caly-xano oc run "@xano-planner Plan a user authentication system" ``` ## Setup Command -The `xano oc setup` command installs everything needed for AI-assisted development: +The `caly-xano oc setup` command installs everything needed for AI-assisted development: ```bash -xano oc setup [options] +caly-xano oc setup [options] ``` ### Options @@ -97,10 +97,10 @@ To get the latest agents, commands, and skills: ```bash # Force re-download all templates -xano oc setup --force +caly-xano oc setup --force # Or update just templates -xano oc update +caly-xano oc update ``` ## Running OpenCode @@ -111,10 +111,10 @@ Start an interactive AI coding session: ```bash # Start OpenCode in the current directory -xano oc run +caly-xano oc run # Start in a specific project directory -xano oc run --workdir /path/to/project +caly-xano oc run --workdir /path/to/project ``` ### With Initial Prompt @@ -123,13 +123,13 @@ Run with a specific task or agent: ```bash # Use a specialized agent -xano oc run "@xano-planner Design a blog backend with posts and comments" +caly-xano oc run "@xano-planner Design a blog backend with posts and comments" # Use a slash command -xano oc run "/xano-table Create a users table with email and password" +caly-xano oc run "/xano-table Create a users table with email and password" # Simple prompt -xano oc run "Help me understand this XanoScript function" +caly-xano oc run "Help me understand this XanoScript function" ``` ### Server Mode @@ -138,13 +138,13 @@ Run OpenCode as an HTTP server for programmatic access: ```bash # Start server on default port (4096) -xano oc serve +caly-xano oc serve # Start on a specific port -xano oc serve --port 8080 +caly-xano oc serve --port 8080 # Start in background (detached) -xano oc serve --detach +caly-xano oc serve --detach ``` ## Agents & Slash Commands @@ -169,16 +169,16 @@ Use `@agent-name` to delegate to specialized agents: ```bash # Plan a feature -xano oc run "@xano-planner Plan a subscription billing system with Stripe" +caly-xano oc run "@xano-planner Plan a subscription billing system with Stripe" # Design a table -xano oc run "@xano-table-designer Create a products table for an e-commerce store" +caly-xano oc run "@xano-table-designer Create a products table for an e-commerce store" # Create an API -xano oc run "@xano-api-writer Create CRUD endpoints for user management" +caly-xano oc run "@xano-api-writer Create CRUD endpoints for user management" # Debug an issue -xano oc run "@debug-helper My API is returning 500 errors on POST requests" +caly-xano oc run "@debug-helper My API is returning 500 errors on POST requests" ``` ### Slash Commands @@ -202,13 +202,13 @@ Use `/command` for quick actions: ```bash # Create a table -xano oc run "/xano-table users with email, password_hash, role enum (admin, user)" +caly-xano oc run "/xano-table users with email, password_hash, role enum (admin, user)" # Create a function -xano oc run "/xano-function calculate_order_total that sums line items with tax" +caly-xano oc run "/xano-function calculate_order_total that sums line items with tax" # Create an API -xano oc run "/xano-api POST /checkout that processes payment and creates order" +caly-xano oc run "/xano-api POST /checkout that processes payment and creates order" ``` ## Skills @@ -243,9 +243,9 @@ Skills provide domain-specific knowledge that agents can reference. They are loa You can reference skills in your prompts: ```bash -xano oc run "Use the xano-security skill to review this login endpoint" +caly-xano oc run "Use the xano-security skill to review this login endpoint" -xano oc run "Apply xano-query-performance patterns to optimize this data fetching" +caly-xano oc run "Apply xano-query-performance patterns to optimize this data fetching" ``` ## Configuration Files @@ -308,7 +308,7 @@ The native host is automatically configured during `xano oc setup`. For manual s ```bash # Install native host manifest -xano oc setup +caly-xano oc setup # The manifest is created at: # Windows: %USERPROFILE%\.calycode\com.calycode.host.json @@ -320,7 +320,7 @@ xano oc setup ```bash # Start native host directly (for debugging) -xano oc native-host +caly-xano oc native-host # The native host listens for JSON messages on stdin # and responds on stdout using Chrome's native messaging protocol @@ -374,7 +374,7 @@ Get-Content -Wait $env:USERPROFILE\.calycode\logs\native-host.log ```bash # Clear template cache and re-download -xano oc setup --force +caly-xano oc setup --force ``` ## Best Practices @@ -391,7 +391,7 @@ xano oc setup --force ```bash # Be specific about what you want -xano oc run "@xano-table-designer Create a products table with: +caly-xano oc run "@xano-table-designer Create a products table with: - name (text, required, max 255) - price (decimal, required, min 0) - description (text, optional) @@ -399,7 +399,7 @@ xano oc run "@xano-table-designer Create a products table with: - created_at (timestamp, auto)" # Provide context -xano oc run "@xano-api-writer Create a checkout API that: +caly-xano oc run "@xano-api-writer Create a checkout API that: - Uses the orders table we just created - Validates cart items exist - Calculates total with tax @@ -412,10 +412,10 @@ For optimization or security-sensitive work, reference the appropriate skill: ```bash # Security review -xano oc run "Use xano-security skill to audit this user registration endpoint" +caly-xano oc run "Use xano-security skill to audit this user registration endpoint" # Performance optimization -xano oc run "Apply xano-query-performance to optimize this dashboard query" +caly-xano oc run "Apply xano-query-performance to optimize this dashboard query" ``` ## Resources diff --git a/util-resources/docs-template/guides/patterns.md b/util-resources/docs-template/guides/patterns.md index f66950fb..60908707 100644 --- a/util-resources/docs-template/guides/patterns.md +++ b/util-resources/docs-template/guides/patterns.md @@ -41,18 +41,18 @@ This guide provides recommendations and points to comprehensive resources. npm install -g @calycode/cli # Initialize for your Xano instance -xano init +caly-xano init # Follow the interactive prompts # Verify setup -xano context show +caly-xano context show ``` ### Version Control Workflow ```bash # Generate repository with XanoScript -xano generate repo \ +caly-xano generate repo \ --instance production \ --workspace main \ --branch live @@ -147,14 +147,14 @@ main (production) 1. **Export XanoScript** before merging: ```bash - xano generate xanoscript --branch feature/new-feature + caly-xano generate xanoscript --branch feature/new-feature ``` 2. **Review in Git** - Use standard PR workflows 3. **Run tests** before deployment: ```bash - xano test run -c ./tests/config.json --branch develop --ci + caly-xano test run -c ./tests/config.json --branch develop --ci ``` ## Architecture Patterns @@ -289,28 +289,28 @@ Found a useful pattern? Share it with the community: ```bash # Initialize CLI -xano init +caly-xano init # Generate repository -xano generate repo +caly-xano generate repo # Extract XanoScript -xano generate xanoscript +caly-xano generate xanoscript # Create registry -xano registry scaffold --output ./my-registry +caly-xano registry scaffold --output ./my-registry # Serve registry locally -xano serve registry --path ./my-registry +caly-xano serve registry --path ./my-registry # Install components -xano registry add component-name --registry +caly-xano registry add component-name --registry # Run tests -xano test run -c ./config.json --ci +caly-xano test run -c ./config.json --ci # Generate documentation -xano generate docs +caly-xano generate docs ``` ### Environment Variables diff --git a/util-resources/docs-template/guides/registry-authoring.md b/util-resources/docs-template/guides/registry-authoring.md index 7c07b6f1..329cbbdf 100644 --- a/util-resources/docs-template/guides/registry-authoring.md +++ b/util-resources/docs-template/guides/registry-authoring.md @@ -42,7 +42,7 @@ The Xano Tools registry system enables you to: ```bash # Create a new registry folder with sample components -xano registry scaffold --output ./my-registry +caly-xano registry scaffold --output ./my-registry ``` This creates: @@ -81,7 +81,7 @@ Edit `items/sample-function/definition.json`: ### 3. Serve Your Registry Locally ```bash -xano serve registry --path ./my-registry +caly-xano serve registry --path ./my-registry ``` Registry available at: `http://localhost:5500/registry/definitions` @@ -90,7 +90,7 @@ Registry available at: `http://localhost:5500/registry/definitions` ```bash # In another terminal, install to your Xano instance -xano registry add my-utils/string-helpers \ +caly-xano registry add my-utils/string-helpers \ --registry http://localhost:5500/registry/definitions \ --instance my-instance \ --workspace main \ @@ -331,7 +331,7 @@ For comprehensive XanoScript documentation, see: ### How Dependencies Work -When you install a component with `xano registry add`: +When you install a component with `caly-xano registry add`: 1. The CLI reads the component's `registryDependencies` array 2. All dependencies are resolved recursively @@ -406,10 +406,10 @@ Components track versions via metadata: ```bash # Terminal 1: Serve your registry -xano serve registry --path ./my-registry +caly-xano serve registry --path ./my-registry # Terminal 2: Test installation -xano registry add my-component \ +caly-xano registry add my-component \ --registry http://localhost:5500/registry/definitions \ --instance test-instance \ --workspace dev \ @@ -470,7 +470,7 @@ Package your registry for npm distribution: "name": "@your-org/xano-registry", "files": ["registry/**"], "scripts": { - "serve": "xano serve registry --path ./registry" + "serve": "caly-xano serve registry --path ./registry" } } ``` @@ -479,7 +479,7 @@ Package your registry for npm distribution: ```bash # Team members install from your registry -xano registry add auth/jwt-verify \ +caly-xano registry add auth/jwt-verify \ --registry https://registry.your-company.com/definitions ``` @@ -496,7 +496,7 @@ For organizations using private npm registries, you can leverage npm's scoped pa "private": true, "files": ["registry/**"], "scripts": { - "serve": "xano serve registry --path ./registry", + "serve": "caly-xano serve registry --path ./registry", "validate": "npx ajv validate -s https://calycode.com/schemas/registry/registry.json -d ./registry/registry.json" }, "publishConfig": { @@ -518,10 +518,10 @@ npm login --registry=https://npm.pkg.github.com --scope=@acme-corp npm install @acme-corp/xano-components # 4. Serve the registry locally from node_modules -xano serve registry --path ./node_modules/@acme-corp/xano-components/registry +caly-xano serve registry --path ./node_modules/@acme-corp/xano-components/registry # 5. Install components from the local registry -xano registry add auth/sso-integration \ +caly-xano registry add auth/sso-integration \ --registry http://localhost:5500/registry/definitions \ --instance production \ --workspace main @@ -529,14 +529,14 @@ xano registry add auth/sso-integration \ **Benefits of NPM Scoped Registries:** -| Feature | Description | -| -------------------- | -------------------------------------------------------------- | -| Access Control | Leverage existing npm org permissions and team roles | -| Version Management | Use npm's semver for registry versioning | -| CI/CD Integration | Easily integrate with existing npm-based pipelines | -| Audit Trail | Track who published what and when via npm audit logs | -| Offline Development | Cache packages locally for air-gapped environments | -| Multi-Registry | Teams can combine public and private registries per scope | +| Feature | Description | +| ------------------- | --------------------------------------------------------- | +| Access Control | Leverage existing npm org permissions and team roles | +| Version Management | Use npm's semver for registry versioning | +| CI/CD Integration | Easily integrate with existing npm-based pipelines | +| Audit Trail | Track who published what and when via npm audit logs | +| Offline Development | Cache packages locally for air-gapped environments | +| Multi-Registry | Teams can combine public and private registries per scope | **Example: Multi-Team Registry Structure** diff --git a/util-resources/docs-template/guides/scaffolding.md b/util-resources/docs-template/guides/scaffolding.md index 2b89d452..b145e33c 100644 --- a/util-resources/docs-template/guides/scaffolding.md +++ b/util-resources/docs-template/guides/scaffolding.md @@ -35,16 +35,16 @@ This approach enables: ```bash # 1. Scaffold a new registry -xano registry scaffold --output ./my-components +caly-xano registry scaffold --output ./my-components # 2. Navigate to the scaffolded registry cd my-components # 3. Serve the registry locally -xano serve registry --path . +caly-xano serve registry --path . # 4. In another terminal, install to your Xano instance -xano registry add sample-function \ +caly-xano registry add sample-function \ --registry http://localhost:5500/registry/definitions \ --instance my-instance \ --workspace main \ @@ -56,7 +56,7 @@ xano registry add sample-function \ ### The Scaffold Command ```bash -xano registry scaffold --output [--instance ] +caly-xano registry scaffold --output [--instance ] ``` **Options:** @@ -232,7 +232,7 @@ For XanoScript syntax and examples, refer to: 1. **Install Xano VS Code Extension** - Best development experience 2. **Extract existing code** - Learn from your existing Xano functions: ```bash - xano generate xanoscript --instance prod --workspace main --branch live + caly-xano generate xanoscript --instance prod --workspace main --branch live ``` 3. **Study extracted files** - Understand XanoScript patterns 4. **Create new components** - Apply patterns to new components @@ -241,7 +241,7 @@ For XanoScript syntax and examples, refer to: ```bash # Extract XanoScript from existing project for reference -xano generate xanoscript \ +caly-xano generate xanoscript \ --instance my-instance \ --workspace main \ --branch live @@ -312,10 +312,10 @@ my-registry/ ```bash # Terminal 1: Serve registry -xano serve registry --path ./my-registry +caly-xano serve registry --path ./my-registry # Terminal 2: Install components -xano registry add auth/login \ +caly-xano registry add auth/login \ --registry http://localhost:5500/registry/definitions \ --instance dev-instance \ --workspace sandbox \ @@ -326,7 +326,7 @@ xano registry add auth/login \ ```bash # Install from hosted registry -xano registry add auth/login utils/string-helpers \ +caly-xano registry add auth/login utils/string-helpers \ --registry https://registry.mycompany.com/definitions \ --instance production \ --workspace main \ @@ -337,7 +337,7 @@ xano registry add auth/login utils/string-helpers \ ```bash # Space-separated list -xano registry add tables/user tables/session auth/login auth/register \ +caly-xano registry add tables/user tables/session auth/login auth/register \ --registry http://localhost:5500/registry/definitions ``` @@ -400,7 +400,7 @@ Bad: ```bash # Always test in a development branch first -xano registry add my-component \ +caly-xano registry add my-component \ --registry http://localhost:5500/registry/definitions \ --instance test \ --workspace dev \ diff --git a/util-resources/docs-template/guides/testing.md b/util-resources/docs-template/guides/testing.md index 9bbc0f04..883e9943 100644 --- a/util-resources/docs-template/guides/testing.md +++ b/util-resources/docs-template/guides/testing.md @@ -33,16 +33,16 @@ The Caly Xano CLI provides a powerful API testing framework that: # test-config.json (see examples below) # 2. Run tests -xano test run -c ./test-config.json +caly-xano test run -c ./test-config.json # 3. Run tests with environment variables -xano test run -c ./test-config.json -e API_KEY=secret -e USER_EMAIL=test@example.com +caly-xano test run -c ./test-config.json -e API_KEY=secret -e USER_EMAIL=test@example.com # 4. Run in CI mode (exit code 1 on failure) -xano test run -c ./test-config.json --ci +caly-xano test run -c ./test-config.json --ci # 5. Run for all API groups -xano test run -c ./test-config.json --all --ci +caly-xano test run -c ./test-config.json --all --ci ``` ## Command Options @@ -398,7 +398,7 @@ When `customAsserts` is empty or not provided, these built-in assertions run: ```bash # Run tests and fail pipeline on errors -xano test run -c ./test-config.json --ci +caly-xano test run -c ./test-config.json --ci ``` ### GitHub Actions Example @@ -432,7 +432,7 @@ jobs: XANO_TEST_PASSWORD: ${{ secrets.TEST_PASSWORD }} XANO_TOKEN_PRODUCTION: ${{ secrets.XANO_TOKEN }} run: | - xano test run \ + caly-xano test run \ -c ./test-config.json \ --instance production \ --workspace main \ @@ -457,7 +457,7 @@ api-tests: before_script: - npm install -g @calycode/cli script: - - xano test run -c ./test-config.json --all --ci + - caly-xano test run -c ./test-config.json --all --ci variables: XANO_TEST_EMAIL: ${TEST_EMAIL} XANO_TEST_PASSWORD: ${TEST_PASSWORD} @@ -561,13 +561,13 @@ tests/ ```bash # Development -xano test run -c ./tests/test-config.dev.js --branch dev +caly-xano test run -c ./tests/test-config.dev.js --branch dev # Staging -xano test run -c ./tests/test-config.staging.js --branch staging +caly-xano test run -c ./tests/test-config.staging.js --branch staging # Production (read-only tests) -xano test run -c ./tests/test-config.prod.js --branch prod --ci +caly-xano test run -c ./tests/test-config.prod.js --branch prod --ci ``` ## Test Results diff --git a/util-resources/docs-template/guides/xanoscript.md b/util-resources/docs-template/guides/xanoscript.md index b86836c6..c8cf9bc0 100644 --- a/util-resources/docs-template/guides/xanoscript.md +++ b/util-resources/docs-template/guides/xanoscript.md @@ -46,7 +46,7 @@ Extract XanoScript from your Xano workspace for version control: ```bash # Extract XanoScript from all supported entities -xano generate xanoscript \ +caly-xano generate xanoscript \ --instance production \ --workspace main \ --branch live @@ -60,7 +60,7 @@ Include XanoScript in your repository structure: ```bash # Generate complete repo with XanoScript -xano generate repo \ +caly-xano generate repo \ --instance production \ --workspace main \ --branch live @@ -88,7 +88,7 @@ Include XanoScript in reusable registry components: Deploy XanoScript-based components to your Xano instance: ```bash -xano registry add utils/jwt-helper \ +caly-xano registry add utils/jwt-helper \ --registry https://registry.example.com/definitions ``` @@ -121,10 +121,10 @@ Xano Tools can process the following XanoScript entity types: ```bash # Extract from current context -xano generate xanoscript +caly-xano generate xanoscript # Extract from specific instance/workspace/branch -xano generate xanoscript \ +caly-xano generate xanoscript \ --instance my-instance \ --workspace my-workspace \ --branch main @@ -165,7 +165,7 @@ Extracted files are organized by entity type: XanoScript is automatically included when generating a repository: ```bash -xano generate repo --instance production --workspace main --branch live +caly-xano generate repo --instance production --workspace main --branch live ``` ## Using XanoScript in Registries @@ -234,10 +234,10 @@ Components can include multiple XanoScript files: ### Recommended Setup 1. **Use the Xano VS Code Extension** - Best experience for XanoScript development -2. **Extract existing code** - Use `xano generate xanoscript` to get your current code +2. **Extract existing code** - Use `caly-xano generate xanoscript` to get your current code 3. **Develop in VS Code** - Edit XanoScript with syntax highlighting 4. **Package in registries** - Create reusable components -5. **Deploy via CLI** - Use `xano registry add` to install +5. **Deploy via CLI** - Use `caly-xano registry add` to install ### VS Code Extension @@ -256,7 +256,7 @@ XanoScript files are text-based and work well with Git: ```bash # Generate XanoScript for version control -xano generate xanoscript --instance prod --workspace main --branch live +caly-xano generate xanoscript --instance prod --workspace main --branch live # Commit changes git add . From 037ca676c546e891cc1f8ba1575f3dbf8b570b31 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mih=C3=A1ly=20T=C3=B3th?= Date: Fri, 10 Apr 2026 10:15:31 +0200 Subject: [PATCH 5/5] chore: pre-release cleanup --- package.json | 3 +++ packages/cli/esbuild.config.ts | 10 ++++++++-- packages/cli/package.json | 3 ++- packages/cli/scripts/installer/install.ps1 | 11 ++++++++--- packages/cli/scripts/installer/install.sh | 4 ++-- packages/cli/src/legacy-xano-command.ts | 4 ++++ packages/xano-skills/README.md | 6 +++--- 7 files changed, 30 insertions(+), 11 deletions(-) create mode 100644 packages/cli/src/legacy-xano-command.ts diff --git a/package.json b/package.json index 3c98341b..ba094068 100644 --- a/package.json +++ b/package.json @@ -17,6 +17,9 @@ "serve-registry": "npx serve registry --listen 3030" }, "private": true, + "engines": { + "node": ">=18.0.0" + }, "publishConfig": { "access": "public" }, diff --git a/packages/cli/esbuild.config.ts b/packages/cli/esbuild.config.ts index 721af684..799624a0 100644 --- a/packages/cli/esbuild.config.ts +++ b/packages/cli/esbuild.config.ts @@ -16,13 +16,19 @@ const distDir = resolve(__dirname, 'dist'); // Bundle the application with esbuild const result = await build({ - entryPoints: [resolve(rootDir, 'src/index.ts')], + entryPoints: { + index: resolve(rootDir, 'src/index.ts'), + 'legacy-xano': resolve(rootDir, 'src/legacy-xano-command.ts'), + }, bundle: true, platform: 'node', plugins: [], target: 'node20', format: 'cjs', - outfile: resolve(distDir, 'index.cjs'), + outdir: distDir, + outExtension: { + '.js': '.cjs', + }, treeShaking: true, minify: true, keepNames: false, diff --git a/packages/cli/package.json b/packages/cli/package.json index 9f2825f3..58849a89 100644 --- a/packages/cli/package.json +++ b/packages/cli/package.json @@ -20,6 +20,7 @@ "developer-tools" ], "bin": { + "xano": "dist/legacy-xano.cjs", "caly-xano": "dist/index.cjs" }, "main": "dist/index.cjs", @@ -60,7 +61,7 @@ "test:coverage": "jest --coverage", "clean": "trash dist tsconfig.tsbuildinfo", "build:js": "tsx esbuild.config.ts", - "build:chmod": "shx chmod +x dist/index.cjs", + "build:chmod": "shx chmod +x dist/index.cjs dist/legacy-xano.cjs", "build": "pnpm clean && pnpm build:js && pnpm build:chmod && pnpm link -g", "bundle:ncc": "pnpm ncc build dist/index.cjs -o dist/cli.cjs && shx cp README.md LICENSE dist/cli.cjs/", "bundle:sea": "tsx build-sea.ts", diff --git a/packages/cli/scripts/installer/install.ps1 b/packages/cli/scripts/installer/install.ps1 index 53664c51..777ac0fd 100644 --- a/packages/cli/scripts/installer/install.ps1 +++ b/packages/cli/scripts/installer/install.ps1 @@ -262,6 +262,10 @@ function Initialize-NativeHost { try { caly-xano opencode init + if ($LASTEXITCODE -ne 0) { + Write-Log "Native host configuration command failed with exit code $LASTEXITCODE" "ERROR" + return $false + } return $true } catch { @@ -275,9 +279,10 @@ function Invoke-Uninstall { Write-Header "Uninstalling CalyCode CLI..." # Remove npm package - if (Get-Command caly-xano -ErrorAction SilentlyContinue) { - Write-Log "Removing $PackageName package..." "INFO" - npm uninstall -g $PackageName 2>$null + Write-Log "Removing $PackageName package..." "INFO" + npm uninstall -g $PackageName 2>$null + if ($LASTEXITCODE -ne 0) { + Write-Log "npm uninstall returned exit code $LASTEXITCODE for $PackageName" "WARN" } # Remove native host configuration diff --git a/packages/cli/scripts/installer/install.sh b/packages/cli/scripts/installer/install.sh index dd6bbf52..4b7580aa 100644 --- a/packages/cli/scripts/installer/install.sh +++ b/packages/cli/scripts/installer/install.sh @@ -97,7 +97,7 @@ uninstall() { header "Uninstalling CalyCode CLI..." # Remove npm package - if command -v caly-xano >/dev/null 2>&1; then + if command -v caly-xano >/dev/null 2>&1 || npm list -g --depth=0 @calycode/cli >/dev/null 2>&1; then log "Removing @calycode/cli package..." npm uninstall -g @calycode/cli 2>/dev/null || sudo npm uninstall -g @calycode/cli 2>/dev/null || true fi @@ -331,7 +331,7 @@ configure_native_host() { if ! command -v caly-xano >/dev/null 2>&1; then warn "Cannot configure native host: 'caly-xano' command not found in PATH" warn "Please restart your terminal and run: caly-xano opencode init" - return 1 + return 0 fi caly-xano opencode init diff --git a/packages/cli/src/legacy-xano-command.ts b/packages/cli/src/legacy-xano-command.ts new file mode 100644 index 00000000..95a2ca29 --- /dev/null +++ b/packages/cli/src/legacy-xano-command.ts @@ -0,0 +1,4 @@ +console.error('The `xano` command is no longer provided by @calycode/cli.'); +console.error('Use `caly-xano` for CalyCode CLI commands.'); +console.error("If you want the official `xano` command, install Xano's official CLI."); +process.exit(1); diff --git a/packages/xano-skills/README.md b/packages/xano-skills/README.md index 763cd45e..896e6c1a 100644 --- a/packages/xano-skills/README.md +++ b/packages/xano-skills/README.md @@ -13,9 +13,9 @@ npx skills add calycode/xano-tools/packages/xano-skills ### Via CalyCode CLI ```bash -xano oc init # Includes skills installation +caly-xano oc init # Includes skills installation # Or separately: -xano oc skills install +caly-xano oc skills install ``` ## Available Skills @@ -34,7 +34,7 @@ xano oc skills install The AI agent will automatically reference these skills when: -- **CLI operations**: Running `xano` commands, generating specs, backups +- **CLI operations**: Running `caly-xano` commands, generating specs, backups - **Database design**: Creating tables, defining schemas, setting up indexes - **API development**: Writing XanoScript, creating endpoints, handling auth - **Performance issues**: Slow queries, N+1 patterns, missing indexes