@nboard-dev/octus 0.3.0

package/src/lib/api.js

@@ -0,0 +1,210 @@
+import got from 'got';
+import { config } from './config.js';
+
+/**
+ * Create configured HTTP client
+ */
+function createClient() {
+  const { apiKey, backendUrl } = config.get();
+  
+  return got.extend({
+    prefixUrl: backendUrl,
+    timeout: { request: 30000 },
+    headers: {
+      'Content-Type': 'application/json',
+      ...(apiKey && { 'X-API-Key': apiKey })
+    },
+    responseType: 'json',
+    throwHttpErrors: false
+  });
+}
+
+/**
+ * Octus API Client
+ * Mirrors the Python CLI's OctusClient
+ */
+export const api = {
+  // ─────────────────────────────────────────────────────────────
+  // Health & Auth
+  // ─────────────────────────────────────────────────────────────
+  
+  async healthCheck() {
+    const client = createClient();
+    const response = await client.get('health');
+    return { ok: response.statusCode === 200, data: response.body };
+  },
+
+  async getMe() {
+    const client = createClient();
+    const response = await client.get('me');
+    if (response.statusCode !== 200) {
+      throw new Error(response.body?.detail || 'Failed to get user info');
+    }
+    return response.body;
+  },
+
+  async getMyOrganization() {
+    const client = createClient();
+    const response = await client.get('me/organization');
+    if (response.statusCode !== 200) {
+      throw new Error(response.body?.detail || 'Failed to get organization');
+    }
+    return response.body;
+  },
+
+  // ─────────────────────────────────────────────────────────────
+  // Repository Lifecycle
+  // ─────────────────────────────────────────────────────────────
+
+  async registerRepository(repoData) {
+    const client = createClient();
+    const response = await client.post('repos/register', { json: repoData });
+    if (response.statusCode !== 200 && response.statusCode !== 201) {
+      throw new Error(response.body?.detail || 'Failed to register repository');
+    }
+    return response.body;
+  },
+
+  async resolveProfile(repoId, gitRemoteUrl) {
+    const client = createClient();
+    const response = await client.post(`repos/${repoId}/resolve-profile`, {
+      json: { git_remote_url: gitRemoteUrl }
+    });
+    if (response.statusCode !== 200) {
+      throw new Error(response.body?.detail || 'Failed to resolve profile');
+    }
+    return response.body;
+  },
+
+  async createInitFile(repoId, profileRef) {
+    const client = createClient();
+    const response = await client.post(`repos/${repoId}/init-file`, {
+      json: { profile_ref: profileRef }
+    });
+    if (response.statusCode !== 200) {
+      throw new Error(response.body?.detail || 'Failed to create init file');
+    }
+    return response.body;
+  },
+
+  // ─────────────────────────────────────────────────────────────
+  // Run Lifecycle
+  // ─────────────────────────────────────────────────────────────
+
+  async verifyInitFile(payload) {
+    const client = createClient();
+    const response = await client.post('runs/verify-init-file', { json: payload });
+    if (response.statusCode !== 200) {
+      throw new Error(response.body?.detail || 'Failed to verify init file');
+    }
+    return response.body;
+  },
+
+  async createRun(runData) {
+    const client = createClient();
+    const response = await client.post('runs', { json: runData });
+    if (response.statusCode !== 200 && response.statusCode !== 201) {
+      throw new Error(response.body?.detail || 'Failed to create run');
+    }
+    return response.body;
+  },
+
+  async getRun(runId) {
+    const client = createClient();
+    const response = await client.get(`runs/${runId}`);
+    if (response.statusCode !== 200) {
+      throw new Error(response.body?.detail || 'Failed to get run');
+    }
+    return response.body;
+  },
+
+  async appendEnvironmentSnapshot(runId, payload) {
+    const client = createClient();
+    const response = await client.post(`runs/${runId}/environment-snapshots`, {
+      json: payload
+    });
+    if (response.statusCode !== 200 && response.statusCode !== 201) {
+      throw new Error(response.body?.detail || 'Failed to append environment snapshot');
+    }
+    return response.body;
+  },
+
+  // ─────────────────────────────────────────────────────────────
+  // Step Lifecycle
+  // ─────────────────────────────────────────────────────────────
+
+  async startStep(stepId, payload) {
+    const client = createClient();
+    const response = await client.post(`steps/${stepId}/start`, { json: payload });
+    if (response.statusCode !== 200) {
+      throw new Error(response.body?.detail || 'Failed to start step');
+    }
+    return response.body;
+  },
+
+  async finishStep(stepId, payload) {
+    const client = createClient();
+    const response = await client.post(`steps/${stepId}/finish`, { json: payload });
+    if (response.statusCode !== 200) {
+      throw new Error(response.body?.detail || 'Failed to finish step');
+    }
+    return response.body;
+  },
+
+  async appendStepLog(stepId, payload) {
+    const client = createClient();
+    const response = await client.post(`steps/${stepId}/logs`, { json: payload });
+    if (response.statusCode !== 200 && response.statusCode !== 201) {
+      throw new Error(response.body?.detail || 'Failed to append step log');
+    }
+    return response.body;
+  },
+
+  async appendStepLogsBatch(stepId, payload) {
+    const client = createClient();
+    const response = await client.post(`steps/${stepId}/logs/batch`, { json: payload });
+    if (response.statusCode !== 200 && response.statusCode !== 201) {
+      throw new Error(response.body?.detail || 'Failed to append step logs batch');
+    }
+    return response.body;
+  },
+
+  // ─────────────────────────────────────────────────────────────
+  // Profiles
+  // ─────────────────────────────────────────────────────────────
+
+  async listProfiles() {
+    const client = createClient();
+    const response = await client.get('profiles');
+    if (response.statusCode !== 200) {
+      throw new Error(response.body?.detail || 'Failed to list profiles');
+    }
+    return response.body;
+  },
+
+  async getProfile(profileKey) {
+    const client = createClient();
+    const response = await client.get(`profiles/${profileKey}`);
+    if (response.statusCode !== 200) {
+      throw new Error(response.body?.detail || 'Failed to get profile');
+    }
+    return response.body;
+  },
+
+  // ─────────────────────────────────────────────────────────────
+  // Blockers
+  // ─────────────────────────────────────────────────────────────
+
+  async getBlockerPatterns(params = {}) {
+    const client = createClient();
+    const searchParams = new URLSearchParams(params).toString();
+    const url = searchParams ? `blockers/patterns?${searchParams}` : 'blockers/patterns';
+    const response = await client.get(url);
+    if (response.statusCode !== 200) {
+      throw new Error(response.body?.detail || 'Failed to get blocker patterns');
+    }
+    return response.body;
+  }
+};
+
+export default api;

package/src/lib/config.js

@@ -0,0 +1,254 @@
+import { homedir, platform } from 'os';
+import { join } from 'path';
+import {
+  chmodSync,
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  unlinkSync,
+  writeFileSync,
+} from 'fs';
+
+const NBOARD_DIR = join(homedir(), '.nboard');
+const STATE_DIR = join(NBOARD_DIR, 'state');
+const CONFIG_FILE = join(NBOARD_DIR, 'config.json');
+const RUN_STATE_FILE = join(STATE_DIR, 'run_state.json');
+const RUN_LOCK_FILE = join(STATE_DIR, 'run.lock');
+const APPROVED_PROFILES_FILE = join(NBOARD_DIR, 'approved_profiles.json');
+
+const LEGACY_DIR = join(homedir(), '.octus');
+const LEGACY_CONFIG_FILE = join(LEGACY_DIR, 'config.toml');
+const LEGACY_STATE_FILE = join(LEGACY_DIR, 'run_state.json');
+const LEGACY_LOCK_FILE = join(LEGACY_DIR, 'run.lock');
+
+function ensureNboardDir() {
+  if (!existsSync(NBOARD_DIR)) {
+    mkdirSync(NBOARD_DIR, { recursive: true });
+    if (platform() !== 'win32') chmodSync(NBOARD_DIR, 0o700);
+  }
+  if (!existsSync(STATE_DIR)) {
+    mkdirSync(STATE_DIR, { recursive: true });
+    if (platform() !== 'win32') chmodSync(STATE_DIR, 0o700);
+  }
+}
+
+function writeSecureFile(filePath, data) {
+  ensureNboardDir();
+  writeFileSync(filePath, JSON.stringify(data, null, 2));
+  if (platform() !== 'win32') chmodSync(filePath, 0o600);
+}
+
+function readJsonFile(filePath, defaultValue = null) {
+  try {
+    if (existsSync(filePath)) {
+      return JSON.parse(readFileSync(filePath, 'utf-8'));
+    }
+  } catch {
+    // ignore corrupted files and fall back
+  }
+  return defaultValue;
+}
+
+function migrateLegacyLayout() {
+  ensureNboardDir();
+
+  if (!existsSync(CONFIG_FILE) && existsSync(LEGACY_CONFIG_FILE)) {
+    try {
+      const content = readFileSync(LEGACY_CONFIG_FILE, 'utf-8');
+      const migrated = {};
+      for (const line of content.split(/\r?\n/)) {
+        const match = line.match(/^\s*([A-Za-z0-9_]+)\s*=\s*"(.*)"\s*$/);
+        if (!match) continue;
+        const [, key, value] = match;
+        if (key === 'api_key' || key === 'backend_url') {
+          migrated[key] = value;
+        }
+      }
+      writeSecureFile(CONFIG_FILE, migrated);
+      unlinkSync(LEGACY_CONFIG_FILE);
+    } catch {
+      // best effort
+    }
+  }
+
+  for (const [legacyPath, currentPath] of [
+    [LEGACY_STATE_FILE, RUN_STATE_FILE],
+    [LEGACY_LOCK_FILE, RUN_LOCK_FILE],
+  ]) {
+    if (!existsSync(currentPath) && existsSync(legacyPath)) {
+      try {
+        copyFileSync(legacyPath, currentPath);
+        if (platform() !== 'win32') chmodSync(currentPath, 0o600);
+        unlinkSync(legacyPath);
+      } catch {
+        // ignore
+      }
+    }
+  }
+
+  try {
+    if (existsSync(LEGACY_DIR) && readdirSync(LEGACY_DIR).length === 0) {
+      rmSync(LEGACY_DIR, { recursive: true, force: true });
+    }
+  } catch {
+    // ignore
+  }
+}
+
+export const config = {
+  get() {
+    migrateLegacyLayout();
+    const envApiKey = process.env.OCTUS_API_TOKEN;
+    const envApiUrl = process.env.OCTUS_API_URL;
+    const fileConfig = readJsonFile(CONFIG_FILE, {});
+
+    return {
+      apiKey: envApiKey || fileConfig.api_key || null,
+      backendUrl: envApiUrl || fileConfig.backend_url || 'http://localhost:8000',
+    };
+  },
+
+  set({ apiKey, backendUrl }) {
+    const current = readJsonFile(CONFIG_FILE, {});
+    const updated = {
+      ...current,
+      ...(apiKey !== undefined && { api_key: apiKey }),
+      ...(backendUrl !== undefined && { backend_url: backendUrl }),
+    };
+    writeSecureFile(CONFIG_FILE, updated);
+  },
+
+  clear() {
+    if (existsSync(NBOARD_DIR)) {
+      rmSync(NBOARD_DIR, { recursive: true, force: true });
+    }
+    if (existsSync(LEGACY_DIR)) {
+      rmSync(LEGACY_DIR, { recursive: true, force: true });
+    }
+  },
+
+  isLoggedIn() {
+    const { apiKey } = this.get();
+    return Boolean(apiKey);
+  },
+
+  getConfigPath() {
+    return CONFIG_FILE;
+  },
+
+  getNboardDir() {
+    return NBOARD_DIR;
+  }
+};
+
+export const runState = {
+  get() {
+    migrateLegacyLayout();
+    return readJsonFile(RUN_STATE_FILE, {
+      run_id: null,
+      profile_hash: null,
+      repo_path: null,
+      steps: {},
+    });
+  },
+
+  set(state) {
+    writeSecureFile(RUN_STATE_FILE, state);
+  },
+
+  clear() {
+    if (existsSync(RUN_STATE_FILE)) {
+      rmSync(RUN_STATE_FILE);
+    }
+  },
+
+  getFilePath() {
+    return RUN_STATE_FILE;
+  }
+};
+
+export const runLock = {
+  STALE_THRESHOLD_MS: 60 * 60 * 1000,
+
+  acquire(force = false) {
+    ensureNboardDir();
+
+    const existing = this.get();
+    if (existing && !force) {
+      const acquiredAt = new Date(existing.acquired_at).getTime();
+      const isStale = Number.isFinite(acquiredAt) && (Date.now() - acquiredAt > this.STALE_THRESHOLD_MS);
+
+      if (!isStale) {
+        if (platform() !== 'win32') {
+          try {
+            process.kill(existing.pid, 0);
+            return { success: false, reason: 'locked', lock: existing };
+          } catch {
+            // process dead; lock stale
+          }
+        } else {
+          return { success: false, reason: 'locked', lock: existing };
+        }
+      }
+    }
+
+    const lock = {
+      pid: process.pid,
+      acquired_at: new Date().toISOString(),
+    };
+    writeSecureFile(RUN_LOCK_FILE, lock);
+    return { success: true, lock };
+  },
+
+  release() {
+    if (existsSync(RUN_LOCK_FILE)) {
+      rmSync(RUN_LOCK_FILE);
+    }
+  },
+
+  get() {
+    return readJsonFile(RUN_LOCK_FILE, null);
+  },
+
+  getFilePath() {
+    return RUN_LOCK_FILE;
+  }
+};
+
+export const approvedProfiles = {
+  get() {
+    return readJsonFile(APPROVED_PROFILES_FILE, {});
+  },
+
+  add(profilePath, sha256, profileName) {
+    const profiles = this.get();
+    profiles[profilePath] = {
+      sha256,
+      approved_at: new Date().toISOString(),
+      profile_name: profileName,
+    };
+    writeSecureFile(APPROVED_PROFILES_FILE, profiles);
+  },
+
+  isApproved(profilePath, sha256) {
+    const profiles = this.get();
+    const record = profiles[profilePath];
+    return Boolean(record && record.sha256 === sha256);
+  },
+
+  getFilePath() {
+    return APPROVED_PROFILES_FILE;
+  }
+};
+
+export default {
+  config,
+  runState,
+  runLock,
+  approvedProfiles,
+  NBOARD_DIR,
+  STATE_DIR,
+};

package/src/lib/octus-contract.js

@@ -0,0 +1,231 @@
+import { createHash, randomUUID } from 'crypto';
+import { existsSync } from 'fs';
+import { basename, join } from 'path';
+import { arch, platform, release } from 'os';
+
+function normalizeText(value) {
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
+}
+
+function mapCategoryToStepType(category) {
+  switch ((category || '').toLowerCase()) {
+    case 'dependency':
+      return 'install';
+    case 'access':
+      return 'auth';
+    case 'verification':
+      return 'verify';
+    default:
+      return 'custom';
+  }
+}
+
+function mapOwner(owner) {
+  const normalized = (owner || '').toLowerCase();
+  if (normalized === 'human' || normalized === 'it' || normalized === 'octo') {
+    return normalized;
+  }
+  return 'octo';
+}
+
+function normalizeStep(rawStep, index) {
+  const key = normalizeText(rawStep.step_key)
+    || normalizeText(rawStep.key)
+    || normalizeText(rawStep.title)
+    || `step_${index}`;
+
+  return {
+    step_index: typeof rawStep.step_index === 'number' ? rawStep.step_index : index,
+    step_key: key.toLowerCase().replace(/[^a-z0-9_]+/g, '_'),
+    step_type: normalizeText(rawStep.step_type) || mapCategoryToStepType(rawStep.category),
+    title: normalizeText(rawStep.title) || normalizeText(rawStep.name) || key,
+    description: normalizeText(rawStep.description),
+    owner: mapOwner(rawStep.owner),
+    command: normalizeText(rawStep.command),
+    retryable: rawStep.retryable !== false,
+    timeout_seconds: Number.isFinite(Number(rawStep.timeout_seconds))
+      ? Math.max(1, Number(rawStep.timeout_seconds))
+      : 300,
+  };
+}
+
+export function normalizeProfile(rawProfile, fallbackName = 'custom') {
+  const steps = Array.isArray(rawProfile?.steps)
+    ? rawProfile.steps.map((step, index) => normalizeStep(step || {}, index))
+    : [];
+
+  return {
+    key: normalizeText(rawProfile?.profile_key) || normalizeText(rawProfile?.key) || null,
+    name: normalizeText(rawProfile?.display_name)
+      || normalizeText(rawProfile?.profile_name)
+      || normalizeText(rawProfile?.name)
+      || fallbackName,
+    version: normalizeText(rawProfile?.version) || 'v1',
+    run_command: normalizeText(rawProfile?.run_command),
+    run_url: normalizeText(rawProfile?.run_url),
+    steps,
+    env_vars_required: Array.isArray(rawProfile?.env_vars_required)
+      ? rawProfile.env_vars_required.filter((item) => typeof item === 'string' && item.trim())
+      : [],
+    raw: rawProfile,
+  };
+}
+
+export function computeProfileHash(profileName, steps) {
+  return createHash('sha256')
+    .update(JSON.stringify({ profileName, steps }))
+    .digest('hex');
+}
+
+export function normalizeInitFilePayload(rawPayload) {
+  const orgId = normalizeText(rawPayload?.org_id);
+  const repoId = normalizeText(rawPayload?.repo_id);
+  const profileRef = normalizeText(rawPayload?.profile_ref);
+  const sig = normalizeText(rawPayload?.sig);
+
+  if (!orgId || !repoId || !profileRef || !sig) {
+    throw new Error('Invalid .octus.yaml — run `octus init` again.');
+  }
+
+  return {
+    org_id: orgId,
+    repo_id: repoId,
+    profile_ref: profileRef,
+    sig,
+  };
+}
+
+export function scanRepository(repoPath) {
+  const projectTypes = [];
+  if (existsSync(join(repoPath, 'package.json'))) projectTypes.push('node');
+  if (existsSync(join(repoPath, 'pyproject.toml')) || existsSync(join(repoPath, 'requirements.txt'))) {
+    projectTypes.push('python');
+  }
+  if (existsSync(join(repoPath, 'Cargo.toml'))) projectTypes.push('rust');
+  if (existsSync(join(repoPath, 'go.mod'))) projectTypes.push('go');
+  if (existsSync(join(repoPath, 'pom.xml'))) projectTypes.push('java');
+  if (existsSync(join(repoPath, 'Gemfile'))) projectTypes.push('ruby');
+  if (existsSync(join(repoPath, 'docker-compose.yml')) || existsSync(join(repoPath, 'docker-compose.yaml'))) {
+    projectTypes.push('docker_compose');
+  }
+
+  return {
+    name: basename(repoPath),
+    path: repoPath,
+    project_type: projectTypes[0] || 'unknown',
+    project_types: projectTypes,
+    has_readme: existsSync(join(repoPath, 'README.md')),
+    has_dockerfile: existsSync(join(repoPath, 'Dockerfile')),
+    has_docker_compose: existsSync(join(repoPath, 'docker-compose.yml')) || existsSync(join(repoPath, 'docker-compose.yaml')),
+    metadata: {
+      project_type: projectTypes[0] || 'unknown',
+    },
+  };
+}
+
+export function buildRunContext({
+  scanResult,
+  repoPath,
+  profileName,
+  profileVersion,
+  resume = false,
+  gitRemoteUrl = null,
+}) {
+  return {
+    repo_name: scanResult.name,
+    repo_path: repoPath,
+    project_type: scanResult.project_type,
+    default_branch: 'main',
+    profile_name: profileName,
+    profile_version: profileVersion,
+    git_remote_url: gitRemoteUrl,
+    user_identifier: null,
+    resume,
+  };
+}
+
+export function buildEnvironmentSnapshot({
+  scanResult,
+  profileName,
+  profileVersion,
+  captureSource = 'cli_setup_start',
+}) {
+  return {
+    capture_source: captureSource,
+    os_name: platform(),
+    os_version: release(),
+    platform: `${platform()} ${release()}`,
+    architecture: arch(),
+    node_version: process.version,
+    shell: process.env.SHELL || process.env.ComSpec || null,
+    metadata: {
+      repo_name: scanResult.name,
+      project_type: scanResult.project_type,
+      profile_name: profileName,
+      profile_version: profileVersion,
+    },
+    captured_at: new Date().toISOString(),
+  };
+}
+
+export function buildRunPayload({
+  repoResponse,
+  currentUser,
+  scanResult,
+  selectedProfile,
+  selectedProfileKey,
+  selectedProfileVersion,
+  profileHash,
+  stepDefs,
+  runContext,
+  environmentSnapshot,
+}) {
+  return {
+    organization_id: repoResponse.organization_id,
+    project_id: repoResponse.id,
+    user_identifier: currentUser.email,
+    role: currentUser.role,
+    profile_version: selectedProfileVersion,
+    profile_hash: profileHash,
+    profile_key: selectedProfileKey || undefined,
+    profile_data: {
+      profile_key: selectedProfileKey || undefined,
+      profile_name: selectedProfile,
+      project_type: scanResult.project_type,
+    },
+    workflow_type: 'onboarding',
+    workflow_name: selectedProfile,
+    trigger_source: 'cli_setup',
+    trigger_actor: currentUser.email,
+    subject_type: 'user',
+    subject_identifier: currentUser.email,
+    run_context: {
+      ...runContext,
+      user_identifier: currentUser.email,
+    },
+    environment_snapshot: environmentSnapshot,
+    steps: stepDefs,
+  };
+}
+
+export function buildLogEntries(stdout, stderr, sequenceStart = 1) {
+  const entries = [];
+  let sequence = sequenceStart;
+
+  for (const [stream, content] of [['stdout', stdout], ['stderr', stderr]]) {
+    if (!content || !String(content).trim()) continue;
+    for (const line of String(content).split(/\r?\n/)) {
+      if (!line.trim()) continue;
+      entries.push({
+        stream,
+        message: line,
+        sequence,
+        ts: new Date().toISOString(),
+        event_id: randomUUID(),
+      });
+      sequence += 1;
+    }
+  }
+
+  return { entries, nextSequence: sequence };
+}