@nboard-dev/octus 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## v0.3.0
+
+Initial Node.js release of `@nboard/octus`.
+
+Highlights:
+- replaces the standard Python/Homebrew installation path for the Octus CLI
+- preserves the core command surface:
+  - `octus login`
+  - `octus logout`
+  - `octus ping`
+  - `octus config`
+  - `octus init`
+  - `octus setup`
+  - `octus doctor`
+  - `octus generate-profile`
+- stores config and runtime state under `~/.nboard/`
+- supports Anthropic-powered onboarding profile generation during `octus init`
+- includes repo-local Octus files:
+  - `.octus.yaml`
+  - `.octus/profile.json`
+  - `.octusignore`

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nBoard Team
+
+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 @@
+# @nboard-dev/octus
+
+[![npm version](https://img.shields.io/npm/v/%40nboard%2Foctus.svg)](https://www.npmjs.com/package/@nboard-dev/octus)
+[![license](https://img.shields.io/npm/l/%40nboard%2Foctus.svg)](./LICENSE)
+
+> AI-powered onboarding for engineering teams
+
+```text
+   ____       __            
+  / __ \____/ /___  _______
+ / / / / __/ __/ / / / ___/
+/ /_/ / /_/ /_/ /_/ (__  ) 
+\____/\__/\__/\__,_/____/  
+```
+
+## Install
+
+```bash
+npm install -g @nboard-dev/octus
+```
+
+Works on **macOS**, **Linux**, and **Windows**.
+
+## Quick Start
+
+```bash
+# 1. Login with your API key
+octus login
+
+# 2. Initialize your repo
+octus init .
+
+# 3. Run onboarding
+octus setup
+
+# 4. Check status
+octus doctor
+```
+
+Or do it all in one command:
+
+```bash
+octus init . --run-setup
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `octus login` | Authenticate with your API key |
+| `octus logout` | Clear stored credentials |
+| `octus ping` | Check connection & auth status |
+| `octus config` | Show current configuration |
+| `octus init [path]` | Initialize a repository |
+| `octus setup [path]` | Run onboarding steps |
+| `octus doctor [path]` | Health check your setup |
+| `octus generate-profile` | Generate a draft profile |
+
+## Migration from Python CLI
+
+`@nboard-dev/octus` is the Node.js replacement for the original Python/Homebrew CLI.
+
+What stays the same:
+- command names (`octus login`, `octus init`, `octus setup`, `octus doctor`)
+- local config directory: `~/.nboard/`
+- repo-local files: `.octus.yaml`, `.octus/profile.json`, `.octusignore`
+
+What changes:
+- install with npm instead of Poetry/Homebrew
+- Node.js 18+ is now the primary runtime
+- AI profile generation uses `@anthropic-ai/sdk` when `ANTHROPIC_API_KEY` is set
+
+## Setup Options
+
+```bash
+# Use a specific profile
+octus setup --profile demo-node
+
+# Skip confirmations (CI mode)
+octus setup --turbo
+
+# Resume a failed run
+octus setup --resume
+
+# Show detailed output
+octus setup --verbose
+
+# Custom timeout per step (seconds)
+octus setup --timeout 600
+```
+
+## Init Options
+
+```bash
+# Clone a repo and init
+octus init https://github.com/org/repo.git
+
+# Clone to specific directory
+octus init https://github.com/org/repo.git -d my-folder
+
+# Init and immediately run setup
+octus init . --run-setup
+```
+
+## Configuration
+
+Octus stores config in `~/.nboard/`:
+
+```text
+~/.nboard/
+├── config.json             # API key & backend URL
+├── approved_profiles.json  # Profile approval records
+└── state/
+    ├── run_state.json      # Current run progress
+    └── run.lock            # Prevents concurrent runs
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `OCTUS_API_TOKEN` | API key (overrides config file) |
+| `OCTUS_API_URL` | Backend URL (overrides config file) |
+| `ANTHROPIC_API_KEY` | Enables AI-generated onboarding profiles during `octus init` |
+
+## Repository Files
+
+Octus creates these files in your repo:
+
+| File | Purpose |
+|------|---------|
+| `.octus.yaml` | Signed init file from backend |
+| `.octus/profile.json` | Local onboarding profile |
+| `.octusignore` | Files to exclude from AI context |
+
+## Requirements
+
+- Node.js 18+
+- Git
+
+## Troubleshooting
+
+### `Not logged in`
+
+```bash
+octus login
+```
+
+### `.octus.yaml not found`
+
+```bash
+octus init .
+```
+
+### AI profile generation fell back to rule-based mode
+
+```bash
+export ANTHROPIC_API_KEY=...
+octus init .
+```
+
+### Backend/auth problems
+
+```bash
+octus config
+octus ping
+```
+
+### Resume a blocked/interrupted onboarding run
+
+```bash
+octus setup --resume
+```
+
+## Links
+
+- [Documentation](https://docs.nboard.tech/cli)
+- [Dashboard](https://demo.nboard.tech)
+- [Support](mailto:support@nboard.tech)
+
+## License
+
+MIT © nBoard Team

package/bin/octus.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { program } from '../src/index.js';
+
+program.parse(process.argv);

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@nboard-dev/octus",
+  "version": "0.3.0",
+  "description": "Octus CLI - AI-powered onboarding for engineering teams",
+  "type": "module",
+  "bin": {
+    "octus": "./bin/octus.js"
+  },
+  "main": "./src/index.js",
+  "scripts": {
+    "start": "node bin/octus.js",
+    "test": "vitest",
+    "lint": "eslint src/ bin/ test/",
+    "build": "echo 'No build step needed for pure JS'"
+  },
+  "keywords": [
+    "octus",
+    "nboard",
+    "onboarding",
+    "cli",
+    "developer-tools",
+    "ai"
+  ],
+  "author": "nBoard Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nboard-team/octus-cli"
+  },
+  "homepage": "https://github.com/nboard-team/octus-cli#readme",
+  "bugs": {
+    "url": "https://github.com/nboard-team/octus-cli/issues"
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/nboard-team"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.24.0",
+    "boxen": "^7.1.1",
+    "chalk": "^5.3.0",
+    "cli-table3": "^0.6.5",
+    "commander": "^12.1.0",
+    "conf": "^12.0.0",
+    "execa": "^9.3.0",
+    "figures": "^6.1.0",
+    "got": "^14.4.1",
+    "inquirer": "^9.2.23",
+    "log-symbols": "^6.0.0",
+    "ora": "^8.0.1",
+    "proper-lockfile": "^4.1.2",
+    "yaml": "^2.4.5"
+  },
+  "devDependencies": {
+    "eslint": "^9.5.0",
+    "vitest": "^1.6.0"
+  }
+}

package/src/commands/config.js

@@ -0,0 +1,29 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { config } from '../lib/config.js';
+import ui from '../lib/ui.js';
+
+export const configCommand = new Command('config')
+  .description('Show current configuration')
+  .action(async () => {
+    ui.header('Octus Configuration');
+
+    const { apiKey, backendUrl } = config.get();
+    const isLoggedIn = config.isLoggedIn();
+
+    ui.divider();
+    ui.keyValue([
+      ['Config file', config.getConfigPath()],
+      ['Data directory', config.getNboardDir()],
+      ['Backend URL', backendUrl || chalk.dim('Not set')],
+      ['API Key', apiKey ? ui.maskSecret(apiKey) : chalk.dim('Not set')],
+      ['Status', isLoggedIn ? chalk.green('Logged in') : chalk.yellow('Not logged in')]
+    ]);
+    ui.divider();
+
+    if (!isLoggedIn) {
+      ui.info('Run `octus login` to authenticate');
+    }
+  });
+
+export default configCommand;

package/src/commands/doctor.js

@@ -0,0 +1,254 @@
+import { Command } from 'commander';
+import { existsSync, readFileSync } from 'fs';
+import { join, resolve } from 'path';
+import { execa } from 'execa';
+import { config, runState } from '../lib/config.js';
+import { api } from '../lib/api.js';
+import ui from '../lib/ui.js';
+
+const DOCTOR_TIMEOUT_MS = 10_000;
+const LOCAL_ENV_FILE_NAME = '.env.local';
+const DISALLOWED_SHELL_TOKENS = new Set([';', '|', '||', '&', '&&', '>', '>>', '<', '<<']);
+const DISALLOWED_SHELL_SUBSTRINGS = ['`', '$(', '${', '\n', '\r'];
+
+function parseEnvLocalKeys(repoPath) {
+  const envPath = join(repoPath, LOCAL_ENV_FILE_NAME);
+  if (!existsSync(envPath)) return new Set();
+
+  return new Set(
+    readFileSync(envPath, 'utf-8')
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter((line) => line && !line.startsWith('#'))
+      .map((line) => (line.startsWith('export ') ? line.slice('export '.length).trim() : line))
+      .filter((line) => line.includes('='))
+      .map((line) => line.split('=', 1)[0].trim())
+      .filter(Boolean)
+  );
+}
+
+function expectedText(step) {
+  return (typeof step.description === 'string' && step.description.trim())
+    ? step.description.trim()
+    : (step.name || step.title || step.key || step.step_key || '').trim() || null;
+}
+
+function validateCheckCommand(checkCommand) {
+  const stripped = checkCommand.trim();
+  if (!stripped) return { valid: false, message: 'Command is empty.' };
+
+  for (const pattern of DISALLOWED_SHELL_SUBSTRINGS) {
+    if (stripped.includes(pattern)) {
+      return { valid: false, message: `Command contains disallowed shell syntax: ${pattern}` };
+    }
+  }
+
+  const tokens = stripped.split(/\s+/);
+  for (const token of tokens) {
+    if (DISALLOWED_SHELL_TOKENS.has(token)) {
+      return { valid: false, message: `Command contains disallowed shell operator: ${token}` };
+    }
+  }
+
+  return { valid: true, tokens };
+}
+
+async function runStepCheck(repoPath, step) {
+  const key = step.key || step.step_key || 'unknown_step';
+  const name = step.name || step.title || key;
+  const safe = validateCheckCommand(step.check_command);
+
+  if (!safe.valid) {
+    return {
+      key,
+      name,
+      expected_text: expectedText(step),
+      passed: false,
+      timed_out: false,
+      actual_text: `Unsafe command rejected: ${safe.message}`,
+    };
+  }
+
+  try {
+    const result = await execa(safe.tokens[0], safe.tokens.slice(1), {
+      cwd: repoPath,
+      timeout: DOCTOR_TIMEOUT_MS,
+      reject: false,
+    });
+    const combined = [result.stdout, result.stderr].filter(Boolean).join('\n').trim();
+    return {
+      key,
+      name,
+      expected_text: expectedText(step),
+      passed: result.exitCode === 0,
+      timed_out: false,
+      actual_text: combined ? combined.replace(/\s+/g, ' ') : (result.exitCode === 0 ? 'passed' : 'failed'),
+    };
+  } catch (error) {
+    if (error.timedOut) {
+      return {
+        key,
+        name,
+        expected_text: expectedText(step),
+        passed: false,
+        timed_out: true,
+        actual_text: null,
+      };
+    }
+
+    return {
+      key,
+      name,
+      expected_text: expectedText(step),
+      passed: false,
+      timed_out: false,
+      actual_text: `Command not found: ${safe.tokens[0]}`,
+    };
+  }
+}
+
+function summarize(checks, envVars) {
+  return {
+    passed: checks.filter((item) => item.passed).length,
+    failed: checks.filter((item) => !item.passed && !item.timed_out).length,
+    timed_out: checks.filter((item) => item.timed_out).length,
+    env_vars_missing: envVars.filter((item) => !item.present).length,
+  };
+}
+
+function renderCheckLine(item) {
+  if (item.timed_out) return `⚠  ${item.key.padEnd(24)} timed out (10s)`;
+  const symbol = item.passed ? '✓' : '✗';
+  const base = item.actual_text || (item.passed ? 'passed' : 'failed');
+  const detail = item.expected_text ? `${base} (expected ${item.expected_text})` : base;
+  return `${symbol}  ${item.key.padEnd(24)} ${detail}`;
+}
+
+function renderEnvVarLine(item) {
+  return `${item.present ? '✓' : '✗'}  ${item.name.padEnd(24)} ${item.present ? 'set' : 'missing'}`;
+}
+
+function doctorExitCode(report) {
+  if (report.summary.failed) return 1;
+  if (report.summary.timed_out) return 1;
+  if (report.summary.env_vars_missing) return 1;
+  return 0;
+}
+
+async function syncDoctorReport(repoPath, report) {
+  const localState = runState.get();
+  if (!localState.run_id) {
+    ui.warning('No saved Octus run id found; skipping doctor sync.');
+    return;
+  }
+  if (localState.repo_path && localState.repo_path !== repoPath) {
+    ui.warning('Saved run state belongs to a different repository; skipping doctor sync.');
+    return;
+  }
+
+  try {
+    await api.appendEnvironmentSnapshot(localState.run_id, {
+      capture_source: 'cli_doctor',
+      node_version: process.version,
+      shell: process.env.SHELL || process.env.ComSpec || null,
+      captured_at: report.checked_at,
+      metadata: {
+        doctor_report: report,
+      },
+    });
+  } catch (error) {
+    ui.warning(`Doctor sync failed: ${error.message}`);
+  }
+}
+
+export const doctorCommand = new Command('doctor')
+  .description('Run a read-only health check against the saved Octus profile')
+  .argument('[path]', 'Path to the repository to check', '.')
+  .option('--sync', 'Best-effort sync of the doctor report to the backend using the saved local run id')
+  .option('--json', 'Print the full doctor report as JSON')
+  .action(async (repoPathArg, options) => {
+    const repoPath = resolve(repoPathArg);
+    if (!existsSync(repoPath)) {
+      ui.error(`Path does not exist: ${repoPath}`);
+      process.exit(1);
+    }
+
+    const profilePath = join(repoPath, '.octus', 'profile.json');
+    if (!existsSync(profilePath)) {
+      ui.error('No Octus profile found. Run octus init . first.');
+      process.exit(1);
+    }
+
+    let profile;
+    try {
+      profile = JSON.parse(readFileSync(profilePath, 'utf-8'));
+    } catch (error) {
+      ui.error(`Invalid Octus profile: ${error.message}`);
+      process.exit(1);
+    }
+
+    const steps = Array.isArray(profile.steps) ? profile.steps : [];
+    const envVarNames = Array.isArray(profile.env_vars_required) ? profile.env_vars_required : [];
+    const envLocalKeys = parseEnvLocalKeys(repoPath);
+    const checks = [];
+
+    for (const step of steps) {
+      if (!step.check_command) continue;
+      checks.push(await runStepCheck(repoPath, step));
+    }
+
+    const envVars = envVarNames.map((name) => ({
+      name,
+      present: Boolean(process.env[name]) || envLocalKeys.has(name),
+    }));
+
+    const report = {
+      repo: repoPath.split('/').pop(),
+      profile_name: profile.profile_name || profile.name || 'unknown',
+      checked_at: new Date().toISOString(),
+      checks,
+      env_vars: envVars,
+      summary: summarize(checks, envVars),
+    };
+
+    if (options.sync && config.isLoggedIn()) {
+      await syncDoctorReport(repoPath, report);
+    }
+
+    if (options.json) {
+      console.log(JSON.stringify(report, null, 2));
+      process.exit(doctorExitCode(report));
+    }
+
+    console.log(`octus doctor — ${report.repo}`);
+    console.log(`Profile: ${report.profile_name}`);
+    console.log(`Checked: ${new Date(report.checked_at).toLocaleString()}`);
+    console.log('ENVIRONMENT HEALTH');
+    console.log('──────────────────────────────────────────');
+    if (report.checks.length === 0) {
+      console.log('No check_command entries found in the saved profile.');
+    } else {
+      report.checks.forEach((item) => console.log(renderCheckLine(item)));
+    }
+    console.log('ENV VARS');
+    console.log('──────────────────────────────────────────');
+    if (report.env_vars.length === 0) {
+      console.log('No required environment variables declared in the saved profile.');
+    } else {
+      report.env_vars.forEach((item) => console.log(renderEnvVarLine(item)));
+    }
+    console.log('SUMMARY');
+    console.log('──────────────────────────────────────────');
+    console.log(
+      `${report.summary.passed} passed  `
+      + `${report.summary.failed} failed  `
+      + `${report.summary.timed_out} timed out  `
+      + `${report.summary.env_vars_missing} env var missing`
+    );
+    console.log('Run octus setup . to apply the latest profile.');
+    console.log('Run octus setup . to fix failing steps.');
+
+    process.exit(doctorExitCode(report));
+  });
+
+export default doctorCommand;

package/src/commands/generate-profile.js

@@ -0,0 +1,46 @@
+import { Command } from 'commander';
+import { existsSync, writeFileSync } from 'fs';
+import { resolve } from 'path';
+import chalk from 'chalk';
+import ui from '../lib/ui.js';
+import { generateRuleBasedProfile, toYamlDraft } from '../lib/profile-generator.js';
+
+export const generateProfileCommand = new Command('generate-profile')
+  .description('Analyze a repository and generate a draft onboarding profile')
+  .argument('[path]', 'Repository path to analyze', '.')
+  .option('-o, --output <file>', 'Output file path (otherwise prints to stdout)')
+  .action(async (pathArg, options) => {
+    const repoPath = resolve(pathArg);
+
+    if (!existsSync(repoPath)) {
+      ui.error(`Path does not exist: ${repoPath}`);
+      process.exit(1);
+    }
+
+    ui.header('Generate Onboarding Profile');
+    ui.info(`Analyzing: ${repoPath}`);
+
+    const spin = ui.spinner('Scanning repository...').start();
+    const { analysis, profile } = generateRuleBasedProfile(repoPath);
+    spin.succeed('Profile generated');
+
+    const yamlOutput = toYamlDraft(profile);
+
+    if (options.output) {
+      writeFileSync(options.output, yamlOutput);
+      ui.success(`Profile saved to: ${options.output}`);
+    } else {
+      ui.divider();
+      console.log(chalk.cyan('─'.repeat(50)));
+      console.log(yamlOutput);
+      console.log(chalk.cyan('─'.repeat(50)));
+    }
+
+    if (analysis.matchesKnownProfile) {
+      ui.divider();
+      ui.warning(`This repo matches the "${analysis.matchesKnownProfile}" profile pattern`);
+      ui.info('Consider using the built-in profile instead of a custom one');
+    }
+  });
+
+export default generateProfileCommand;