@indigoai-us/hq-cli 5.115.0 → 5.115.2

package/dist/lib/onboarding/cli/onboard.js

@@ -0,0 +1,135 @@
+/**
+ * CLI onboard entry point (VLT-9 US-002; vendored from @indigoai-us/hq-onboarding).
+ *
+ * Programmatic API for the /onboard command. The slash command calls
+ * these functions; they can also be consumed by integration tests.
+ */
+import { VaultClient, VaultConflictError, VaultNotFoundError } from "@indigoai-us/hq-cloud";
+import { createCompanyFlow, joinCompanyFlow, resumeOnboarding, } from "../orchestrator.js";
+import { readCheckpoint, getCheckpointPath } from "../checkpoint.js";
+import { formatProgress, formatSummary, formatError } from "./prompts.js";
+const CREATE_STEPS = 6;
+const JOIN_STEPS = 6;
+/**
+ * Decide whether `create-company` may proceed for a slug.
+ *
+ * A company that already exists in the CALLER's namespace is not "taken": it
+ * is theirs — typically left behind by an earlier run that created the
+ * entity and then died before the bucket, membership, or config were done
+ * (there may be no local checkpoint or company folder at all). The flow
+ * resumes against it instead of refusing. Only a slug held by a different
+ * account is refused.
+ */
+export async function checkCompanySlugAvailability(client, slug) {
+    const mine = await client.entity.findInMyNamespace("company", slug);
+    if (mine)
+        return { kind: "mine", uid: mine.uid };
+    try {
+        await client.entity.findBySlug("company", slug);
+        return { kind: "taken" };
+    }
+    catch (err) {
+        // VaultNotFoundError = slug available, continue
+        const isNotFound = err instanceof VaultNotFoundError ||
+            (err instanceof Error && err.name === "VaultNotFoundError");
+        if (isNotFound)
+            return { kind: "available" };
+        // Several other tenants hold the slug (server answers 409): not ours.
+        const isConflict = err instanceof VaultConflictError ||
+            (err instanceof Error && err.name === "VaultConflictError");
+        if (isConflict)
+            return { kind: "taken" };
+        throw err;
+    }
+}
+/**
+ * Run the /onboard CLI flow.
+ */
+export async function runOnboardCli(options) {
+    const { mode, vaultConfig, hqRoot, log = console.log } = options;
+    let stepCounter = 0;
+    const onProgress = (event) => {
+        if (event.status === "running")
+            stepCounter++;
+        const total = mode === "create-company" ? CREATE_STEPS : JOIN_STEPS;
+        log(formatProgress(event, stepCounter, total));
+    };
+    const config = { vaultConfig, hqRoot };
+    try {
+        if (mode === "resume") {
+            const checkpoint = await readCheckpoint(hqRoot);
+            if (!checkpoint) {
+                return { success: false, error: "No checkpoint found. Run /onboard to start." };
+            }
+            log(`Resuming ${checkpoint.mode} flow from step ${checkpoint.completedSteps.length + 1}...`);
+            const result = await resumeOnboarding(config, onProgress);
+            log("");
+            log(formatSummary(result));
+            return { success: true, result };
+        }
+        if (mode === "dry-run") {
+            log("DRY RUN — simulating create-company flow:");
+            log("  1. Create person entity");
+            log("  2. Create company entity");
+            log("  3. Provision S3 bucket + KMS key");
+            log("  4. Bootstrap owner membership");
+            log("  5. Verify STS credential vending");
+            log("  6. Write .hq/config.json");
+            log("");
+            log("No resources will be created. Run /onboard to execute.");
+            return { success: true };
+        }
+        if (mode === "create-company") {
+            // Validate slug availability
+            if (options.companySlug) {
+                const client = new VaultClient(vaultConfig);
+                const availability = await checkCompanySlugAvailability(client, options.companySlug);
+                if (availability.kind === "taken") {
+                    return {
+                        success: false,
+                        error: `Company slug "${options.companySlug}" is already taken. Choose another.`,
+                    };
+                }
+                if (availability.kind === "mine") {
+                    log(`Company "${options.companySlug}" already exists in your account (${availability.uid}) — finishing its setup.`);
+                }
+            }
+            const input = {
+                mode: "create-company",
+                personName: options.personName,
+                personEmail: options.personEmail,
+                companyName: options.companyName,
+                companySlug: options.companySlug,
+            };
+            log(`Creating company "${input.companyName}" (${input.companySlug})...`);
+            log("");
+            const result = await createCompanyFlow(input, config, onProgress);
+            log("");
+            log(formatSummary(result));
+            return { success: true, result };
+        }
+        if (mode === "join-company") {
+            const input = {
+                mode: "join-company",
+                personName: options.personName,
+                personEmail: options.personEmail,
+                inviteToken: options.inviteToken,
+            };
+            log("Joining company via invite...");
+            log("");
+            const result = await joinCompanyFlow(input, config, onProgress);
+            log("");
+            log(formatSummary(result));
+            return { success: true, result };
+        }
+        return { success: false, error: `Unknown mode: ${mode}` };
+    }
+    catch (err) {
+        const checkpointPath = getCheckpointPath(hqRoot);
+        const errorMsg = err instanceof Error ? err.message : String(err);
+        log("");
+        log(formatError(err instanceof Error ? err : new Error(errorMsg), checkpointPath));
+        return { success: false, error: errorMsg };
+    }
+}
+//# sourceMappingURL=onboard.js.map

package/dist/lib/onboarding/cli/prompts.d.ts

@@ -0,0 +1,28 @@
+/**
+ * CLI prompt helpers for /onboard command (VLT-9 US-002; vendored from @indigoai-us/hq-onboarding).
+ *
+ * Provides typed prompt interfaces the slash command can call.
+ * These are library functions — the actual UX is in onboard.md.
+ */
+import type { OnboardingResult, OnboardingProgress } from "../types.js";
+/**
+ * Format a progress event for CLI display.
+ */
+export declare function formatProgress(event: OnboardingProgress, stepNumber: number, totalSteps: number): string;
+/**
+ * Format the success summary box.
+ */
+export declare function formatSummary(result: OnboardingResult): string;
+/**
+ * Format an error for CLI display with recovery hints.
+ */
+export declare function formatError(error: Error, checkpointPath: string): string;
+/**
+ * Validate a company slug: lowercase, alphanumeric + hyphens, 3-40 chars.
+ */
+export declare function validateSlug(slug: string): string | null;
+/**
+ * Validate email format.
+ */
+export declare function validateEmail(email: string): string | null;
+//# sourceMappingURL=prompts.d.ts.map

package/dist/lib/onboarding/cli/prompts.js

@@ -0,0 +1,83 @@
+/**
+ * CLI prompt helpers for /onboard command (VLT-9 US-002; vendored from @indigoai-us/hq-onboarding).
+ *
+ * Provides typed prompt interfaces the slash command can call.
+ * These are library functions — the actual UX is in onboard.md.
+ */
+/**
+ * Format a progress event for CLI display.
+ */
+export function formatProgress(event, stepNumber, totalSteps) {
+    const statusIcon = {
+        pending: "○",
+        running: "◉",
+        done: "✓",
+        skipped: "→",
+        failed: "✗",
+    }[event.status];
+    const detail = event.detail ? ` — ${event.detail}` : "";
+    return `  ${statusIcon} Step ${stepNumber}/${totalSteps}: ${event.step}${detail}`;
+}
+/**
+ * Format the success summary box.
+ */
+export function formatSummary(result) {
+    const lines = [
+        "┌─────────────────────────────────────────────┐",
+        "│  HQ Onboarding Complete                     │",
+        "├─────────────────────────────────────────────┤",
+        `│  Company:  ${result.companySlug.padEnd(33)}│`,
+        `│  UID:      ${result.companyUid.padEnd(33)}│`,
+        `│  Person:   ${result.personUid.padEnd(33)}│`,
+        `│  Role:     ${result.role.padEnd(33)}│`,
+    ];
+    if (result.bucketName) {
+        lines.push(`│  Bucket:   ${result.bucketName.padEnd(33)}│`);
+    }
+    lines.push("├─────────────────────────────────────────────┤");
+    lines.push("│  Next steps:                                │");
+    if (result.role === "owner") {
+        lines.push("│    • Run /invite <email> to add team        │");
+        lines.push("│    • Run hq sync to push files              │");
+    }
+    else {
+        lines.push("│    • Run hq sync to pull latest files       │");
+    }
+    lines.push("└─────────────────────────────────────────────┘");
+    return lines.join("\n");
+}
+/**
+ * Format an error for CLI display with recovery hints.
+ */
+export function formatError(error, checkpointPath) {
+    const lines = [
+        `ERROR: ${error.message}`,
+        "",
+        `Checkpoint saved to: ${checkpointPath}`,
+        "To retry: /onboard --resume",
+    ];
+    return lines.join("\n");
+}
+/**
+ * Validate a company slug: lowercase, alphanumeric + hyphens, 3-40 chars.
+ */
+export function validateSlug(slug) {
+    if (slug.length < 3)
+        return "Slug must be at least 3 characters";
+    if (slug.length > 40)
+        return "Slug must be at most 40 characters";
+    if (!/^[a-z0-9][a-z0-9-]*[a-z0-9]$/.test(slug)) {
+        return "Slug must be lowercase alphanumeric with hyphens (e.g. 'my-company')";
+    }
+    return null;
+}
+/**
+ * Validate email format.
+ */
+export function validateEmail(email) {
+    if (!email.includes("@") || !email.includes(".")) {
+        return "Invalid email format";
+    }
+    return null;
+}
+//# sourceMappingURL=prompts.js.map

package/dist/lib/onboarding/errors.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Onboarding error classes (VLT-9 US-001; vendored from @indigoai-us/hq-onboarding).
+ *
+ * Each failure class maps to a distinct step in the onboarding flow,
+ * making it easy for the installer to show targeted recovery hints.
+ */
+export declare class OnboardingError extends Error {
+    readonly step: string;
+    readonly cause?: Error | undefined;
+    constructor(message: string, step: string, cause?: Error | undefined);
+}
+export declare class PersonCreationError extends OnboardingError {
+    constructor(message: string, cause?: Error);
+}
+export declare class CompanyCreationError extends OnboardingError {
+    constructor(message: string, cause?: Error);
+}
+export declare class ProvisioningError extends OnboardingError {
+    constructor(message: string, cause?: Error);
+}
+export declare class MembershipBootstrapError extends OnboardingError {
+    constructor(message: string, cause?: Error);
+}
+export declare class FirstSyncError extends OnboardingError {
+    constructor(message: string, cause?: Error);
+}
+export declare class InviteAcceptError extends OnboardingError {
+    constructor(message: string, cause?: Error);
+}
+export declare class StsVerifyError extends OnboardingError {
+    constructor(message: string, cause?: Error);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/lib/onboarding/errors.js

@@ -0,0 +1,59 @@
+/**
+ * Onboarding error classes (VLT-9 US-001; vendored from @indigoai-us/hq-onboarding).
+ *
+ * Each failure class maps to a distinct step in the onboarding flow,
+ * making it easy for the installer to show targeted recovery hints.
+ */
+export class OnboardingError extends Error {
+    step;
+    cause;
+    constructor(message, step, cause) {
+        super(message);
+        this.step = step;
+        this.cause = cause;
+        this.name = "OnboardingError";
+    }
+}
+export class PersonCreationError extends OnboardingError {
+    constructor(message, cause) {
+        super(message, "create-person", cause);
+        this.name = "PersonCreationError";
+    }
+}
+export class CompanyCreationError extends OnboardingError {
+    constructor(message, cause) {
+        super(message, "create-company", cause);
+        this.name = "CompanyCreationError";
+    }
+}
+export class ProvisioningError extends OnboardingError {
+    constructor(message, cause) {
+        super(message, "provision-bucket", cause);
+        this.name = "ProvisioningError";
+    }
+}
+export class MembershipBootstrapError extends OnboardingError {
+    constructor(message, cause) {
+        super(message, "bootstrap-membership", cause);
+        this.name = "MembershipBootstrapError";
+    }
+}
+export class FirstSyncError extends OnboardingError {
+    constructor(message, cause) {
+        super(message, "first-sync", cause);
+        this.name = "FirstSyncError";
+    }
+}
+export class InviteAcceptError extends OnboardingError {
+    constructor(message, cause) {
+        super(message, "accept-invite", cause);
+        this.name = "InviteAcceptError";
+    }
+}
+export class StsVerifyError extends OnboardingError {
+    constructor(message, cause) {
+        super(message, "verify-sts", cause);
+        this.name = "StsVerifyError";
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/lib/onboarding/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Onboarding orchestrator (formerly the npm package `@indigoai-us/hq-onboarding`,
+ * vendored into hq-cli in 2026-09 because nobody owned the package and its
+ * company-create step no longer matched the vault-service's authorization).
+ *
+ * Composes entities, bucket provisioning, STS, sync, membership, and
+ * invite/accept into create-company and join-company flows with
+ * checkpoint/resume.
+ */
+export { createCompanyFlow, joinCompanyFlow, resumeOnboarding, onboardingContract, } from "./orchestrator.js";
+export { readCheckpoint, writeCheckpoint, deleteCheckpoint, getCheckpointPath, isStepComplete, } from "./checkpoint.js";
+export { OnboardingError, PersonCreationError, CompanyCreationError, ProvisioningError, MembershipBootstrapError, FirstSyncError, InviteAcceptError, StsVerifyError, } from "./errors.js";
+export type { OnboardingInput, CreateCompanyInput, JoinCompanyInput, OnboardingConfig, OnboardingResult, OnboardingProgress, OnboardingStep, StepStatus, ProgressCallback, OnboardingCheckpoint, DesktopInstallerContract, HqConfig, } from "./types.js";
+export { runOnboardCli } from "./cli/onboard.js";
+export type { OnboardCliOptions, OnboardCliResult } from "./cli/onboard.js";
+export { formatProgress, formatSummary, formatError, validateSlug, validateEmail } from "./cli/prompts.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/onboarding/index.js

@@ -0,0 +1,16 @@
+/**
+ * Onboarding orchestrator (formerly the npm package `@indigoai-us/hq-onboarding`,
+ * vendored into hq-cli in 2026-09 because nobody owned the package and its
+ * company-create step no longer matched the vault-service's authorization).
+ *
+ * Composes entities, bucket provisioning, STS, sync, membership, and
+ * invite/accept into create-company and join-company flows with
+ * checkpoint/resume.
+ */
+export { createCompanyFlow, joinCompanyFlow, resumeOnboarding, onboardingContract, } from "./orchestrator.js";
+export { readCheckpoint, writeCheckpoint, deleteCheckpoint, getCheckpointPath, isStepComplete, } from "./checkpoint.js";
+export { OnboardingError, PersonCreationError, CompanyCreationError, ProvisioningError, MembershipBootstrapError, FirstSyncError, InviteAcceptError, StsVerifyError, } from "./errors.js";
+// CLI
+export { runOnboardCli } from "./cli/onboard.js";
+export { formatProgress, formatSummary, formatError, validateSlug, validateEmail } from "./cli/prompts.js";
+//# sourceMappingURL=index.js.map

package/dist/lib/onboarding/orchestrator.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Onboarding orchestrator (VLT-9 US-001; vendored from @indigoai-us/hq-onboarding).
+ *
+ * Composes VLT-1 (entities), VLT-2 (bucket provisioning), VLT-3 (STS),
+ * VLT-5 (sync), VLT-6 (membership), and VLT-7 (invite/accept) into two
+ * end-to-end flows:
+ *
+ *   createCompanyFlow — founder creates a new company + vault
+ *   joinCompanyFlow   — invitee accepts an invite and syncs
+ *
+ * Each step is idempotent via checkpoint/resume. Progress events are
+ * emitted via callback for the installer UI.
+ */
+import type { CreateCompanyInput, JoinCompanyInput, OnboardingConfig, OnboardingResult, ProgressCallback, DesktopInstallerContract } from "./types.js";
+/**
+ * Create-company flow for founders.
+ *
+ * Steps:
+ *   1. Create person entity
+ *   2. Create company entity (the vault-service makes the caller its owner)
+ *   3. Provision bucket + KMS via vault-service
+ *   4. Bootstrap owner membership (library-direct, bypasses handler auth)
+ *   5. Verify STS vend works end-to-end
+ *   6. Write .hq/config.json
+ */
+export declare function createCompanyFlow(input: CreateCompanyInput, config: OnboardingConfig, onProgress?: ProgressCallback): Promise<OnboardingResult>;
+/**
+ * Join-company flow for invitees.
+ *
+ * Steps:
+ *   1. Parse invite token
+ *   2. Create person entity (if not already registered)
+ *   3. Accept invite
+ *   4. Verify STS vend
+ *   5. First sync to pull initial vault contents
+ *   6. Write .hq/config.json
+ */
+export declare function joinCompanyFlow(input: JoinCompanyInput, config: OnboardingConfig, onProgress?: ProgressCallback): Promise<OnboardingResult>;
+/**
+ * Resume an interrupted onboarding flow from checkpoint.
+ */
+export declare function resumeOnboarding(config: OnboardingConfig, onProgress?: ProgressCallback): Promise<OnboardingResult>;
+/**
+ * Desktop installer contract implementation.
+ */
+export declare const onboardingContract: DesktopInstallerContract;
+//# sourceMappingURL=orchestrator.d.ts.map