rainbo 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Rainbo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,183 @@
+# rainbo
+
+Rainbo command line tools for data migration workflows.
+
+## Requirements
+
+- Node.js 16+
+- Rust toolchain for source development. End users installing from npm get a prebuilt binary.
+
+## Install
+
+```bash
+npm install -g rainbo
+rainbo version
+```
+
+## Development
+
+```bash
+node packaging/npm/run.js version
+node packaging/npm/run.js help
+npm run check:skills
+npm run build:npm:local
+```
+
+## Output
+
+Command output is structured for humans, scripts, and AI agents:
+
+```bash
+rainbo version                 # JSON envelope on stdout
+rainbo version --format pretty # Human-readable output
+```
+
+Successful JSON output uses:
+
+```json
+{"ok":true,"data":{...}}
+```
+
+Errors are written to stderr:
+
+```json
+{"ok":false,"error":{"type":"validation","subtype":"invalid_argument","message":"..."}}
+```
+
+## Update
+
+```bash
+rainbo update --check
+rainbo update
+rainbo update --force
+```
+
+`update --check` only reports status. Normal JSON command output may include
+`_notice.update` when a newer npm version is known from the local update cache
+and `_notice.skills` when locally synced skills are out of sync with the
+running binary. Both notices recommend `rainbo update`.
+
+`update` detects npm installations, runs `npm install -g rainbo@<latest>`
+when auto-update is available, verifies the new binary, and syncs repository
+skills with:
+
+```bash
+npx skills add git@gitlab.clickzetta-inc.com:ee/rainbo.git -y -g
+```
+
+Skill sync records detailed state in `skills-state.json` and updates installed
+official skills incrementally when possible. If incremental planning is not
+available, it falls back to a full install.
+
+If automatic update is unavailable, the JSON action is `manual_required` and
+the response includes release and changelog URLs.
+
+## Auth
+
+```bash
+rainbo auth connect "rainbo://connect?base_url=http%3A%2F%2Flocalhost%3A8088&code=..."
+rainbo auth status
+rainbo auth logout
+```
+
+Generate the connection URL from the logged-in Rainbo web UI user menu. `auth
+connect` exchanges the one-time connection code for a revocable CLI bearer token
+and stores it under `~/.config/rainbo/auth.json` with `0600` permissions on
+Unix-like systems.
+
+## API Commands
+
+Authenticated API commands reuse the session created by `rainbo auth connect`.
+Complex request bodies can be passed with `--data-json`, `--data-file`, or
+`--data @payload.json`.
+
+```bash
+rainbo data-sync cmt-jobs --data-file cmt-jobs.json
+rainbo data-verify lineage-verify-table --data-file verify-table.json
+rainbo toolbox sql-debug --datasource-id 1 --sql "select 1"
+rainbo toolbox lineage-spark --data-file lineage-spark.json
+
+rainbo lineage graph create --data-file lineage-graph.json
+rainbo lineage graph get "lineage_graph:migration:1001"
+rainbo lineage graph --view-mode TABLE_GRAPH --graph-key "lineage_graph:migration:1001"
+rainbo lineage upstream "lakehouse.dwd.user" --graph-key "lineage_graph:migration:1001" --side TARGET --depth 1
+rainbo lineage downstream "lakehouse.ods.user" --graph-key "lineage_graph:migration:1001" --side TARGET --depth 1
+rainbo lineage graph delete "lineage_graph:migration:1001"
+```
+
+## Release
+
+1. Update `package.json` and `rust/Cargo.toml` to the same version.
+2. Export the npm publish token from the release machine:
+
+```bash
+source ~/.zshrc
+export NPM_TOKEN="${NPM_TOKEN}"
+```
+
+`NODE_AUTH_TOKEN` is also supported. Use a granular access token with read/write
+access and "Bypass two-factor authentication" enabled. The publish script
+requires token-based publishing, creates a temporary npm config, verifies
+`npm whoami --registry` returns `singdata`, and refuses to publish any package
+whose `package.json` name is not `rainbo`.
+
+3. Build, verify, dry-run pack, and publish from this directory:
+
+```bash
+npm run publish:npm:local
+```
+
+If npm returns `EOTP`, use an automation-capable publish token or pass the
+current OTP:
+
+```bash
+npm run publish:npm:local -- --otp=<code>
+```
+
+By default the local script builds the current platform binary into
+`packaging/npm/bin/<platform>/`. To publish multiple bundled platforms from a
+machine with the required Rust targets/toolchains installed, set:
+
+```bash
+RAINBO_NPM_BUILD_TARGETS=darwin-arm64,darwin-x64 npm run publish:npm:local
+```
+
+The package source lives under the Rainbo GitLab repository as
+`packages/rainbo-cli`; npm publishing is intentionally local and does not depend
+on a separate repository or CI workflow.
+
+## Skills
+
+Repository skills live in `skills/`. They can be installed from the repository:
+
+```bash
+npx skills add git@gitlab.clickzetta-inc.com:ee/rainbo.git -y -g
+```
+
+`git@gitlab.clickzetta-inc.com:ee/rainbo.git` is the skills repository
+source used by `rainbo update`. The old aggregate `rainbo-cli` skill has
+been removed; current Rainbo skills use focused names such as `rainbo-auth`.
+
+New Rainbo skills should follow the style in the repository-level
+`skill-template/`: the top-level
+`SKILL.md` acts as a routing and safety rulebook, while detailed command
+families live in `references/*.md`. Authenticated workflow skills should point
+to `rainbo-auth` first instead of duplicating session rules.
+
+## Project layout
+
+`packages/rainbo-cli/`:
+
+```text
+rust/             Rust CLI implementation
+Cargo.toml        Cargo workspace for the Rust CLI
+packaging/npm/    npm binary bundler and bin launcher
+scripts/          local npm publishing and skill format checks
+```
+
+Repository root:
+
+```text
+skills/           Rainbo skills installable with `npx skills add`
+skill-template/   Template for new Rainbo skills
+```

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "rainbo",
+  "version": "0.1.0",
+  "description": "Rainbo command line tools for data migration workflows",
+  "bin": {
+    "rainbo": "packaging/npm/run.js"
+  },
+  "scripts": {
+    "build:release": "cargo build --release --workspace",
+    "build:npm:local": "node scripts/build-npm-local.js",
+    "check:skills": "node scripts/skill-format-check/index.js",
+    "pack:npm:local": "npm run build:npm:local && npm pack --dry-run",
+    "publish:npm:local": "bash scripts/publish-npm-local.sh",
+    "test": "cargo test --workspace && node packaging/npm/run.js version && node packaging/npm/run.js help"
+  },
+  "os": [
+    "darwin",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "license": "MIT",
+  "files": [
+    "packaging/npm/bin",
+    "packaging/npm/platform.js",
+    "packaging/npm/run.js",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/packaging/npm/platform.js

@@ -0,0 +1,37 @@
+const PLATFORM_PACKAGES = {
+  "darwin-x64": {
+    target: "x86_64-apple-darwin",
+    binary: "rainbo",
+    os: "darwin",
+    cpu: "x64",
+    archiveExt: ".tar.xz",
+  },
+  "darwin-arm64": {
+    target: "aarch64-apple-darwin",
+    binary: "rainbo",
+    os: "darwin",
+    cpu: "arm64",
+    archiveExt: ".tar.xz",
+  },
+  "win32-x64": {
+    target: "x86_64-pc-windows-msvc",
+    binary: "rainbo.exe",
+    os: "win32",
+    cpu: "x64",
+    archiveExt: ".zip",
+  },
+};
+
+function currentPlatformKey() {
+  return `${process.platform}-${process.arch}`;
+}
+
+function currentPlatformPackage() {
+  return PLATFORM_PACKAGES[currentPlatformKey()];
+}
+
+module.exports = {
+  PLATFORM_PACKAGES,
+  currentPlatformKey,
+  currentPlatformPackage,
+};

package/packaging/npm/run.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+
+const { spawnSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+const { currentPlatformKey, currentPlatformPackage } = require("./platform");
+
+const isWindows = process.platform === "win32";
+const repoRoot = path.join(__dirname, "..", "..");
+const sourceManifest = path.join(repoRoot, "rust", "Cargo.toml");
+
+function resolveBundledLauncher() {
+  const platformPackage = currentPlatformPackage();
+  if (!platformPackage) return null;
+  const launcher = path.join(__dirname, "bin", currentPlatformKey(), platformPackage.binary);
+  return fs.existsSync(launcher) ? launcher : null;
+}
+
+function resolveLauncher() {
+  if (fs.existsSync(sourceManifest)) return null;
+  const bundledLauncher = resolveBundledLauncher();
+  if (bundledLauncher) return bundledLauncher;
+  return null;
+}
+
+function installIfMissing() {
+  if (resolveLauncher() || fs.existsSync(sourceManifest)) return;
+  const platformPackage = currentPlatformPackage();
+  const packageHint = platformPackage
+    ? `${currentPlatformKey()} binary`
+    : `unsupported platform ${currentPlatformKey()}`;
+  console.error(`rainbo binary package is missing for ${currentPlatformKey()}.`);
+  console.error(`Expected bundled npm binary: ${packageHint}`);
+  console.error("Rebuild and reinstall the npm package from packages/rainbo-cli.");
+  process.exit(1);
+}
+
+function recoverWindowsOldLauncher() {
+  // Kept as a no-op so older npm-launched processes can upgrade cleanly.
+}
+
+recoverWindowsOldLauncher();
+installIfMissing();
+
+const useSource = fs.existsSync(sourceManifest);
+const command = useSource ? "cargo" : resolveLauncher();
+const args = useSource
+  ? ["run", "--quiet", "--manifest-path", sourceManifest, "--", ...process.argv.slice(2)]
+  : process.argv.slice(2);
+if (!command) process.exit(1);
+const result = spawnSync(command, args, { stdio: "inherit", shell: isWindows });
+
+if (result.error) {
+  console.error(result.error.message);
+  process.exit(1);
+}
+process.exit(result.status || 0);