@hyperdrive.bot/cli 1.0.12 → 1.0.16

package/dist/commands/module/sync.js

@@ -0,0 +1,409 @@
+/**
+ * Module Sync Command
+ *
+ * Generates structured architecture summaries for modules.
+ * For each module: clone → detect _bmad or invoke Claude → validate YAML → upload via API.
+ * Replaces the deprecated `project sync` command with module-level ownership.
+ */
+import { Args, Command, Flags } from '@oclif/core';
+import chalk from 'chalk';
+import { execFileSync, spawn } from 'child_process';
+import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync } from 'fs';
+import yaml from 'js-yaml';
+import ora from 'ora';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { HyperdriveSigV4Service } from '../../services/hyperdrive-sigv4.js';
+// ============================================================================
+// Architecture Summary YAML Schema & Validation (inline for CLI — no server deps)
+// ============================================================================
+const VALID_ENTITY_TYPES = ['client', 'company', 'delivery', 'initiative', 'module', 'service', 'system', 'tool'];
+const REQUIRED_SUMMARY_KEYS = ['module', 'domains', 'patterns', 'tech_stack'];
+const ARCHITECTURE_YAML_SCHEMA = `module:
+  name: "<module-name>"
+  description: "<one-line description>"
+
+domains:
+  - name: "<domain-name>"
+    modules: [<module1>, <module2>]
+    key_files: [<path1>, <path2>]
+
+patterns:
+  handler_pattern: "<glob pattern for handlers>"
+  service_pattern: "<glob pattern for services>"
+  module_config: "<glob pattern for module config>"
+  test_pattern: "<glob pattern for tests>"
+
+entity_registry:
+  - { name: "<entity-name>", type: "<client|company|delivery|initiative|module|service|system|tool>", path: "<relative-path>" }
+
+tech_stack:
+  runtime: "<e.g. nodejs-22>"
+  framework: "<e.g. serverless-v4>"
+  language: "<e.g. typescript>"
+  database: "<e.g. dynamodb>"`;
+const ARCHITECTURE_ANALYSIS_PROMPT = `Analyze this code repository and produce a structured module architecture summary in YAML format. Output ONLY valid YAML — no markdown fences, no explanations, no commentary.
+
+Analyze the following:
+1. Directory structure and key files
+2. Functional domains (groups of related modules)
+3. Code patterns (handler paths, service paths, test paths, module config paths)
+4. Entity registry (named entities with type: client|company|delivery|initiative|module|service|system|tool)
+5. Technology stack (runtime, framework, language, database)
+
+Required YAML schema:
+${ARCHITECTURE_YAML_SCHEMA}
+
+Now analyze the repository and produce the YAML summary.`;
+const VALID_REPO_NAME_REGEX = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+const MAX_BMAD_DOC_SIZE = 100 * 1024; // 100KB cap for _bmad docs (SEC-002 mitigation)
+export default class ModuleSync extends Command {
+    static args = {
+        module: Args.string({
+            description: 'Module slug',
+            required: false,
+        }),
+    };
+    static description = 'Generate architecture summaries for modules via Claude analysis';
+    static examples = [
+        '<%= config.bin %> module sync my-module',
+        '<%= config.bin %> module sync my-module --json',
+        '<%= config.bin %> module sync --all',
+        '<%= config.bin %> module sync --all --json',
+    ];
+    static flags = {
+        all: Flags.boolean({
+            description: 'Sync all modules in the tenant',
+            exclusive: ['module'],
+        }),
+        domain: Flags.string({
+            char: 'd',
+            description: 'Tenant domain (for multi-domain setups)',
+        }),
+        json: Flags.boolean({
+            description: 'Output result as JSON',
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(ModuleSync);
+        if (!args.module && !flags.all) {
+            this.error('Provide a module slug or use --all to sync all modules.');
+        }
+        // Authenticate
+        let service;
+        const authSpinner = ora('Checking authentication...').start();
+        try {
+            service = new HyperdriveSigV4Service(flags.domain);
+            authSpinner.succeed('Authenticated');
+        }
+        catch (error) {
+            authSpinner.fail('Not authenticated');
+            this.error(`${error.message}\n\nPlease authenticate first with: ${chalk.cyan('hd auth login')}`);
+        }
+        if (flags.all) {
+            // --all mode: sync all modules
+            await this.syncAllModules(service, flags);
+        }
+        else {
+            // Single module sync
+            await this.syncSingleModule(service, args.module, flags);
+        }
+    }
+    async syncAllModules(service, flags) {
+        const listSpinner = ora('Fetching modules...').start();
+        let modules;
+        try {
+            modules = await service.moduleList();
+            listSpinner.succeed(`Found ${modules.length} module(s)`);
+        }
+        catch (error) {
+            listSpinner.fail('Failed to fetch modules');
+            this.error(`Could not list modules: ${error.message}`);
+        }
+        if (modules.length === 0) {
+            if (flags.json) {
+                this.log(JSON.stringify({ results: [], summary: { failed: 0, succeeded: 0, total: 0 } }, null, 2));
+            }
+            else {
+                this.log(chalk.yellow('No modules to sync.'));
+            }
+            return;
+        }
+        this.log('');
+        this.log(chalk.blue(`Syncing ${modules.length} module(s)...`));
+        this.log('');
+        const results = [];
+        for (let i = 0; i < modules.length; i++) {
+            const mod = modules[i];
+            const slug = mod.slug || mod.name || `module-${i}`;
+            const prefix = chalk.dim(`[${i + 1}/${modules.length}]`);
+            const result = await this.syncModule(service, slug, prefix);
+            results.push(result);
+        }
+        // Summary
+        this.log('');
+        const succeeded = results.filter(r => r.status === 'success').length;
+        const failed = results.filter(r => r.status === 'failed').length;
+        if (flags.json) {
+            this.log(JSON.stringify({ results, summary: { failed, succeeded, total: modules.length } }, null, 2));
+            return;
+        }
+        if (failed === 0) {
+            this.log(chalk.green(`Synced ${succeeded}/${modules.length} modules (0 failed)`));
+        }
+        else {
+            this.log(chalk.yellow(`Synced ${succeeded}/${modules.length} modules (${failed} failed)`));
+            for (const r of results.filter(r => r.status === 'failed')) {
+                this.log(chalk.red(`  ${r.slug}: ${r.error}`));
+            }
+        }
+    }
+    async syncSingleModule(service, moduleSlug, flags) {
+        const result = await this.syncModule(service, moduleSlug, '');
+        if (flags.json) {
+            this.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        if (result.status === 'failed') {
+            // Error already displayed by syncModule
+        }
+    }
+    async syncModule(service, moduleSlug, prefix) {
+        const label = prefix ? `${prefix} ${chalk.cyan(moduleSlug)}` : chalk.cyan(moduleSlug);
+        const spinner = ora(`${label} — resolving...`).start();
+        let tmpDir = null;
+        try {
+            // Step 1: Resolve module by slug
+            const mod = await service.moduleGet({ slug: moduleSlug });
+            const sourceLocation = mod.sourceLocation;
+            if (!sourceLocation) {
+                throw new Error('Module has no sourceLocation configured — cannot clone');
+            }
+            // Validate the slug for path safety
+            const safeName = mod.slug || moduleSlug;
+            if (!VALID_REPO_NAME_REGEX.test(safeName)) {
+                throw new Error(`Invalid module slug "${safeName}" — must match ${VALID_REPO_NAME_REGEX}`);
+            }
+            // Step 2: Clone the module repo
+            spinner.text = `${label} — cloning...`;
+            tmpDir = mkdtempSync(join(tmpdir(), `hd-sync-${safeName}-`));
+            const clonePath = join(tmpDir, safeName);
+            try {
+                execFileSync('git', ['clone', '--depth', '1', sourceLocation, clonePath], {
+                    stdio: 'pipe',
+                    timeout: 120_000, // 2 min clone timeout
+                });
+            }
+            catch (cloneError) {
+                throw new Error(`git clone failed: ${cloneError.stderr?.toString() || cloneError.message}`);
+            }
+            // Step 3: Detect _bmad or generate via Claude
+            spinner.text = `${label} — analyzing...`;
+            let yamlOutput = null;
+            let lastError = null;
+            const MAX_ATTEMPTS = 3;
+            // Check for _bmad docs
+            const bmadDocPath = this.detectBmadDocs(clonePath);
+            for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+                try {
+                    if (bmadDocPath) {
+                        // Use _bmad doc with simpler restructure prompt
+                        const docStat = statSync(bmadDocPath);
+                        if (docStat.size > MAX_BMAD_DOC_SIZE) {
+                            throw new Error(`_bmad doc exceeds ${MAX_BMAD_DOC_SIZE / 1024}KB size limit (${Math.round(docStat.size / 1024)}KB) — skipping to full analysis`);
+                        }
+                        const docContent = readFileSync(bmadDocPath, 'utf-8');
+                        const prompt = `You are given an existing architecture documentation file. Convert it into the following YAML format. Output ONLY valid YAML, no markdown fences, no explanations.\n\nRequired YAML schema:\n${ARCHITECTURE_YAML_SCHEMA}\n\nHere is the architecture document to convert:\n\n<architecture-doc>\n${docContent}\n</architecture-doc>`;
+                        yamlOutput = await this.runClaude(prompt, clonePath);
+                    }
+                    else {
+                        // Full codebase analysis
+                        yamlOutput = await this.runClaude(ARCHITECTURE_ANALYSIS_PROMPT, clonePath);
+                    }
+                    // Validate
+                    this.validateYaml(yamlOutput);
+                    break; // Validation passed
+                }
+                catch (error) {
+                    lastError = error.message;
+                    this.log(chalk.dim(`  ${safeName} attempt ${attempt}/${MAX_ATTEMPTS} failed: ${lastError}`));
+                    yamlOutput = null;
+                    if (attempt === MAX_ATTEMPTS) {
+                        throw new Error(`Validation failed after ${MAX_ATTEMPTS} attempts: ${lastError}`);
+                    }
+                }
+            }
+            if (!yamlOutput) {
+                throw new Error(`Generation failed: ${lastError}`);
+            }
+            // Step 4: Extract entity registry and merge with gut config
+            spinner.text = `${label} — extracting entities...`;
+            const parsedYaml = yaml.load(yamlOutput);
+            let entityRegistry = (parsedYaml.entity_registry || []);
+            // Check for .gut/config.json and merge
+            const gutEntities = this.readGutEntities(clonePath);
+            if (gutEntities.length > 0) {
+                entityRegistry = this.mergeEntityRegistries(entityRegistry, gutEntities);
+                this.log(chalk.dim(`  ${safeName}: merged ${entityRegistry.length} entities (${gutEntities.length} from gut)`));
+            }
+            else if (entityRegistry.length > 0) {
+                this.log(chalk.dim(`  ${safeName}: found ${entityRegistry.length} entities from analysis`));
+            }
+            // Step 5: Upload via moduleUpdateContext API
+            spinner.text = `${label} — uploading...`;
+            await service.moduleUpdateContext(moduleSlug, {
+                architectureSummary: yamlOutput,
+                entityRegistry,
+                lastSyncedAt: new Date().toISOString(),
+            });
+            spinner.succeed(`${label} — ${chalk.green('done')}`);
+            return { slug: moduleSlug, status: 'success' };
+        }
+        catch (error) {
+            spinner.fail(`${label} — ${chalk.red('failed')}`);
+            this.log(chalk.red(`  Error: ${error.message}`));
+            return { error: error.message, slug: moduleSlug, status: 'failed' };
+        }
+        finally {
+            // Cleanup temp directory
+            if (tmpDir && existsSync(tmpDir)) {
+                try {
+                    rmSync(tmpDir, { force: true, recursive: true });
+                }
+                catch {
+                    // Ignore cleanup errors
+                }
+            }
+        }
+    }
+    detectBmadDocs(repoPath) {
+        const bmadDir = join(repoPath, '_bmad');
+        if (!existsSync(bmadDir))
+            return null;
+        try {
+            if (!statSync(bmadDir).isDirectory())
+                return null;
+            const files = readdirSync(bmadDir);
+            const archPatterns = [/^architecture.*\.md$/i, /^arch-.*\.md$/i];
+            for (const file of files) {
+                for (const pattern of archPatterns) {
+                    if (pattern.test(file)) {
+                        return join(bmadDir, file);
+                    }
+                }
+            }
+        }
+        catch {
+            // Ignore fs errors
+        }
+        return null;
+    }
+    runClaude(prompt, cwd) {
+        return new Promise((resolve, reject) => {
+            const TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
+            const child = spawn('claude', ['-p', prompt, '--output-format', 'text'], {
+                cwd,
+                stdio: ['pipe', 'pipe', 'pipe'],
+                timeout: TIMEOUT_MS,
+            });
+            let stdout = '';
+            let stderr = '';
+            child.stdout.on('data', (data) => {
+                stdout += data.toString();
+            });
+            child.stderr.on('data', (data) => {
+                stderr += data.toString();
+            });
+            child.on('error', (error) => {
+                reject(new Error(`Claude CLI failed to start: ${error.message}`));
+            });
+            child.on('close', (code) => {
+                if (code !== 0) {
+                    reject(new Error(`Claude CLI exited with code ${code}: ${stderr.slice(0, 500)}`));
+                    return;
+                }
+                // Strip markdown code fences if present
+                let output = stdout.trim();
+                if (output.startsWith('```yaml')) {
+                    output = output.replace(/^```yaml\n?/, '').replace(/\n?```$/, '');
+                }
+                else if (output.startsWith('```')) {
+                    output = output.replace(/^```\n?/, '').replace(/\n?```$/, '');
+                }
+                resolve(output);
+            });
+        });
+    }
+    validateYaml(yamlString) {
+        const parsed = yaml.load(yamlString);
+        if (!parsed || typeof parsed !== 'object') {
+            throw new Error('YAML must be a non-null object');
+        }
+        for (const key of REQUIRED_SUMMARY_KEYS) {
+            if (!(key in parsed)) {
+                throw new Error(`Missing required top-level key: '${key}'`);
+            }
+        }
+        const mod = parsed.module;
+        if (!mod || typeof mod !== 'object' || !mod.name || !mod.description) {
+            throw new Error("'module' must have 'name' and 'description' string fields");
+        }
+        if (!Array.isArray(parsed.domains)) {
+            throw new Error("'domains' must be an array");
+        }
+        if (!parsed.patterns || typeof parsed.patterns !== 'object') {
+            throw new Error("'patterns' must be an object");
+        }
+        // entity_registry is optional but must be an array if present
+        if ('entity_registry' in parsed) {
+            if (!Array.isArray(parsed.entity_registry)) {
+                throw new Error("'entity_registry' must be an array");
+            }
+            for (let i = 0; i < parsed.entity_registry.length; i++) {
+                const entry = parsed.entity_registry[i];
+                if (!entry.name)
+                    throw new Error(`entity_registry[${i}]: 'name' is required`);
+                if (!entry.type)
+                    throw new Error(`entity_registry[${i}]: 'type' is required`);
+                if (!VALID_ENTITY_TYPES.includes(entry.type)) {
+                    throw new Error(`entity_registry[${i}]: invalid type '${entry.type}'`);
+                }
+                if (!entry.path)
+                    throw new Error(`entity_registry[${i}]: 'path' is required`);
+            }
+        }
+        const techStack = parsed.tech_stack;
+        if (!techStack || typeof techStack !== 'object') {
+            throw new Error("'tech_stack' must be an object");
+        }
+    }
+    readGutEntities(repoPath) {
+        const gutConfigPath = join(repoPath, '.gut', 'config.json');
+        if (!existsSync(gutConfigPath))
+            return [];
+        try {
+            const content = readFileSync(gutConfigPath, 'utf-8');
+            const config = JSON.parse(content);
+            if (!config.entities || !Array.isArray(config.entities))
+                return [];
+            return config.entities
+                .filter((e) => e && typeof e === 'object' && e.name && e.type && e.path &&
+                VALID_ENTITY_TYPES.includes(e.type))
+                .map((e) => ({
+                name: e.name,
+                path: e.path,
+                type: e.type,
+                ...(e.repository && typeof e.repository === 'string' ? { repository: e.repository } : {}),
+                ...(e.description && typeof e.description === 'string' ? { description: e.description } : {}),
+            }));
+        }
+        catch {
+            return [];
+        }
+    }
+    mergeEntityRegistries(claudeEntities, gutEntities) {
+        const gutNameSet = new Set(gutEntities.map(e => e.name.toLowerCase()));
+        const uniqueClaude = claudeEntities.filter(e => !gutNameSet.has(e.name.toLowerCase()));
+        return [...gutEntities, ...uniqueClaude];
+    }
+}

package/dist/commands/module/unlink.d.ts

@@ -0,0 +1,11 @@
+import { Command } from '@oclif/core';
+export default class ModuleUnlink extends Command {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        domain: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        originSlug: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        targetSlug: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/module/unlink.js

@@ -0,0 +1,77 @@
+import { Command, Flags } from '@oclif/core';
+import chalk from 'chalk';
+import { HyperdriveSigV4Service } from '../../services/hyperdrive-sigv4.js';
+export default class ModuleUnlink extends Command {
+    static description = 'Remove a dependency link between two modules';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> --originSlug="my-frontend" --targetSlug="my-api"',
+    ];
+    static flags = {
+        domain: Flags.string({
+            char: 'd',
+            description: 'Tenant domain (for multi-domain setups)',
+        }),
+        originSlug: Flags.string({
+            description: 'Slug of the module to remove the dependency from',
+            required: true,
+        }),
+        targetSlug: Flags.string({
+            description: 'Slug of the dependency to remove',
+            required: true,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(ModuleUnlink);
+        if (flags.originSlug === flags.targetSlug) {
+            this.log(chalk.red('❌ Error: originSlug and targetSlug must be different'));
+            this.exit(1);
+        }
+        this.log(chalk.yellow(`🔗 Unlinking ${flags.originSlug} -/-> ${flags.targetSlug}...`));
+        try {
+            const service = new HyperdriveSigV4Service(flags.domain);
+            const result = await service.moduleUnlink({
+                originSlug: flags.originSlug,
+                targetSlug: flags.targetSlug,
+            });
+            this.log('');
+            this.log(chalk.green(`✅ Module unlink successful!`));
+            this.log('');
+            this.log(chalk.gray(`Removed dependency: ${chalk.cyan(flags.originSlug)} no longer depends on ${chalk.cyan(flags.targetSlug)}`));
+            this.log(chalk.gray(`Deployment waves will be recalculated on next mission launch.`));
+            this.log('');
+            // Show remaining targets if any
+            const targets = result.targets || {};
+            const remaining = Object.keys(targets);
+            if (remaining.length > 0) {
+                this.log(chalk.gray('Remaining dependencies:'));
+                for (const target of remaining) {
+                    const params = typeof targets[target] === 'object' ? Object.keys(targets[target]).join(', ') : '';
+                    this.log(chalk.gray(`  → ${chalk.cyan(target)} (${params})`));
+                }
+            }
+            else {
+                this.log(chalk.gray('No remaining dependencies for this module.'));
+            }
+        }
+        catch (error) {
+            this.log('');
+            this.log(chalk.red('❌ Error unlinking modules'));
+            if (error.response?.data?.message) {
+                this.log(chalk.red('Error: ' + error.response.data.message));
+            }
+            else if (error.message) {
+                this.log(chalk.red('Error: ' + error.message));
+            }
+            else {
+                this.log(chalk.red('Error: ' + error.toString()));
+            }
+            if (error.response?.status === 404) {
+                this.log('');
+                this.log(chalk.yellow('💡 Tip: Make sure the link exists'));
+                this.log(chalk.gray(`   Check with: hd module get --slug=${flags.originSlug}`));
+            }
+            this.log('');
+            this.exit(1);
+        }
+    }
+}

package/dist/commands/module/update.d.ts

@@ -10,18 +10,28 @@ export default class ModuleUpdate extends Command {
         buildRuntimeVersion: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         ciService: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         defaultBranch: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        dependsOn: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         deploymentStrategy: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        dockerBuild: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'deploy-command': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         domain: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         framework: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         installCommand: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        postDeployCommand: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        postDeployFailureMode: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'module-type': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         name: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         routeDiscovery: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'runtime-mode': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         runCommand: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         runtime: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'runtime-config': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         runtimeVersion: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        show: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         slug: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         sourceDirectory: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         sourceLocation: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        subdomain: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
 }