@hyperdrive.bot/cli 1.0.13 → 1.0.17

package/dist/commands/project/sync.js

@@ -1,78 +1,20 @@
 /**
- * Project Sync Command
+ * Project Sync Command (DEPRECATED)
  *
- * Generates structured architecture summaries for repos in a project.
- * For each repo: clone/pull → detect _bmad or invoke Claude → validate YAML → upload S3 → update DynamoDB.
+ * This command has been replaced by `hd module sync`.
+ * Kept in place to show deprecation warning to users of the old workflow.
  */
 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 = ['repo', 'domains', 'patterns', 'modules', 'entity_registry', 'tech_stack'];
-const ARCHITECTURE_YAML_SCHEMA = `repo:
-  name: "<repo-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>"
-
-modules: [<module1>, <module2>, ...]
-
-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>"
-  infrastructure: "<e.g. aws-lambda>"`;
-const ARCHITECTURE_ANALYSIS_PROMPT = `Analyze this code repository and produce a structured 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. List of modules/packages
-5. Entity registry (named entities with type: client|company|delivery|initiative|module|service|system|tool)
-6. Technology stack (runtime, framework, language, database, infrastructure)
-
-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 ProjectSync extends Command {
     static args = {
         project: Args.string({
-            description: 'Project slug or ID',
-            required: true,
+            description: 'Project slug or ID (deprecated)',
+            required: false,
         }),
     };
-    static description = 'Generate architecture summaries for project repos via Claude analysis';
-    static examples = [
-        '<%= config.bin %> project sync my-project',
-        '<%= config.bin %> project sync my-project --repo api',
-        '<%= config.bin %> project sync my-project --json',
-    ];
+    static description = '[DEPRECATED] Use "module sync" instead';
+    static hidden = true;
     static flags = {
         domain: Flags.string({
             char: 'd',
@@ -86,321 +28,10 @@ export default class ProjectSync extends Command {
         }),
     };
     async run() {
-        const { args, flags } = await this.parse(ProjectSync);
-        // 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')}`);
-        }
-        // Resolve project by slug
-        const projectSpinner = ora(`Resolving project ${chalk.cyan(args.project)}...`).start();
-        let project;
-        try {
-            const result = await service.moduleGet({ slug: args.project });
-            project = { name: result.name || args.project, projectId: result.projectId || args.project, slug: result.slug || args.project };
-            projectSpinner.succeed(`Project: ${chalk.cyan(project.name)} (${project.slug})`);
-        }
-        catch (error) {
-            projectSpinner.fail('Project not found');
-            this.error(`Could not find project "${args.project}": ${error.response?.data?.message || error.message}`);
-        }
-        // List repos
-        const repoSpinner = ora('Fetching repositories...').start();
-        let repos;
-        try {
-            repos = await service.projectListRepos(project.projectId);
-            repoSpinner.succeed(`Found ${repos.length} repo(s)`);
-        }
-        catch (error) {
-            repoSpinner.fail('Failed to fetch repos');
-            this.error(`Could not list repos: ${error.response?.data?.message || error.message}`);
-        }
-        // Filter by --repo flag
-        if (flags.repo) {
-            repos = repos.filter(r => r.name === flags.repo);
-            if (repos.length === 0) {
-                this.error(`No repo named "${flags.repo}" found in project "${project.slug}"`);
-            }
-        }
-        if (repos.length === 0) {
-            this.log(chalk.yellow('No repositories to sync.'));
-            return;
-        }
-        this.log('');
-        this.log(chalk.blue(`Syncing ${repos.length} repo(s)...`));
-        this.log('');
-        // Process each repo
-        const results = [];
-        for (let i = 0; i < repos.length; i++) {
-            const repo = repos[i];
-            const prefix = chalk.dim(`[${i + 1}/${repos.length}]`);
-            const result = await this.syncRepo(service, project, repo, prefix);
-            results.push(result);
-        }
-        // Summary
-        this.log('');
-        const succeeded = results.filter(r => r.success).length;
-        const failed = results.filter(r => !r.success).length;
-        if (flags.json) {
-            this.log(JSON.stringify({ failed, project: project.slug, results, succeeded, total: repos.length }, null, 2));
-            return;
-        }
-        if (failed === 0) {
-            this.log(chalk.green(`Synced ${succeeded}/${repos.length} repos (0 failed)`));
-        }
-        else {
-            this.log(chalk.yellow(`Synced ${succeeded}/${repos.length} repos (${failed} failed)`));
-            for (const r of results.filter(r => !r.success)) {
-                this.log(chalk.red(`  ${r.name}: ${r.error}`));
-            }
-        }
-    }
-    async syncRepo(service, project, repo, prefix) {
-        const spinner = ora(`${prefix} ${chalk.cyan(repo.name)} — cloning...`).start();
-        let tmpDir = null;
-        try {
-            // Step 1: Validate repo name and clone
-            if (!VALID_REPO_NAME_REGEX.test(repo.name)) {
-                throw new Error(`Invalid repo name "${repo.name}" — must match ${VALID_REPO_NAME_REGEX}`);
-            }
-            tmpDir = mkdtempSync(join(tmpdir(), `hd-sync-${repo.name}-`));
-            const clonePath = join(tmpDir, repo.name);
-            try {
-                execFileSync('git', ['clone', '--depth', '1', '--branch', repo.defaultBranch, repo.gitRemote, clonePath], {
-                    stdio: 'pipe',
-                    timeout: 120_000, // 2 min clone timeout
-                });
-            }
-            catch (cloneError) {
-                throw new Error(`git clone failed: ${cloneError.stderr?.toString() || cloneError.message}`);
-            }
-            // Step 2: Detect _bmad or generate via Claude
-            spinner.text = `${prefix} ${chalk.cyan(repo.name)} — 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(`  ${repo.name} 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 2b: Extract entity registry from validated YAML and merge with gut config
-            spinner.text = `${prefix} ${chalk.cyan(repo.name)} — 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(`  ${repo.name}: merged ${entityRegistry.length} entities (${gutEntities.length} from gut)`));
-            }
-            else if (entityRegistry.length > 0) {
-                this.log(chalk.dim(`  ${repo.name}: found ${entityRegistry.length} entities from analysis`));
-            }
-            // Step 3: Upload to S3 via API
-            spinner.text = `${prefix} ${chalk.cyan(repo.name)} — uploading...`;
-            // The API handles S3 upload and DynamoDB update — call updateRepo with the summary content
-            await service.projectUpdateRepo(project.projectId, repo.repoId, {
-                architectureSummary: yamlOutput,
-                lastSyncedAt: new Date().toISOString(),
-            });
-            // Step 4: Update entity registry via dedicated endpoint
-            if (entityRegistry.length > 0) {
-                try {
-                    await service.projectUpdateEntities(project.projectId, repo.repoId, entityRegistry);
-                }
-                catch (entityError) {
-                    this.log(chalk.yellow(`  ${repo.name}: entity registry update failed: ${entityError.message}`));
-                }
-            }
-            spinner.succeed(`${prefix} ${chalk.cyan(repo.name)} — ${chalk.green('done')}`);
-            return { name: repo.name, success: true };
-        }
-        catch (error) {
-            spinner.fail(`${prefix} ${chalk.cyan(repo.name)} — ${chalk.red('failed')}`);
-            this.log(chalk.red(`  Error: ${error.message}`));
-            return { error: error.message, name: repo.name, success: false };
-        }
-        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 repo = parsed.repo;
-        if (!repo || typeof repo !== 'object' || !repo.name || !repo.description) {
-            throw new Error("'repo' 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");
-        }
-        if (!Array.isArray(parsed.modules)) {
-            throw new Error("'modules' must be an array");
-        }
-        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");
-        }
-        for (const field of ['runtime', 'framework', 'language', 'database', 'infrastructure']) {
-            if (!techStack[field]) {
-                throw new Error(`tech_stack.${field} is required`);
-            }
-        }
-    }
-    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,
-                type: e.type,
-                path: e.path,
-                ...(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];
+        this.warn(`${chalk.yellow("⚠️  'hd project sync' is deprecated.")} Use ${chalk.cyan("'hd module sync {module}'")} instead.\n\n` +
+            `Examples:\n` +
+            `  ${chalk.cyan('hd module sync my-module')}       Sync a single module\n` +
+            `  ${chalk.cyan('hd module sync --all')}            Sync all modules\n` +
+            `  ${chalk.cyan('hd module sync my-module --json')} JSON output\n`);
     }
 }

package/dist/commands/seed.d.ts

@@ -0,0 +1,93 @@
+import { Command } from '@oclif/core';
+/**
+ * Context passed to every per-app seed script function.
+ *
+ * Apps own per-app schema knowledge — this CLI is the orchestrator. Each app
+ * declares its seed phases by exporting a default object from
+ * `apps/<app>/scripts/seed.ts` shaped like {@link AppSeedScript}.
+ */
+export interface AppSeedContext {
+    /** Stage slug (e.g. `feat-e2e-expansion`). */
+    stage: string;
+    /** Source Postgres schema to copy data from (e.g. `public`). */
+    fromSchema: string;
+    /** Target Postgres schema to migrate + seed (defaults to `stage`). */
+    toSchema: string;
+    /** Per-stage CloudFront hostname for the FE Lambda Container (used for `professores.domain` etc.). */
+    cfDomain: string;
+    /** App slug currently running (one of `--apps`). */
+    app: string;
+}
+/** Result of a single phase. `sql` empty string => phase is a no-op for this app. */
+export interface AppSeedPhaseResult {
+    sql: string;
+    /** Optional human-readable description for `--dry-run` output. */
+    description?: string;
+}
+/**
+ * Contract every app's `apps/<app>/scripts/seed.ts` must export as `default`.
+ *
+ * Each phase returns SQL that the orchestrator submits to the `hd service seed`
+ * Lambda (in-VPC psql runner). Apps that don't need a phase should return
+ * `{ sql: '' }`.
+ *
+ * @example
+ * ```ts
+ * // apps/core/scripts/seed.ts
+ * import type { AppSeedContext, AppSeedScript } from '@hyperdrive.bot/cli/seed'
+ *
+ * const seed: AppSeedScript = {
+ *   async runMigrations(ctx) {
+ *     return { sql: `CREATE SCHEMA IF NOT EXISTS "${ctx.toSchema}"; ...` }
+ *   },
+ *   async copyData(ctx) {
+ *     const tables = ['alunos', 'professores', 'cursos']
+ *     const sql = tables.map(t =>
+ *       `INSERT INTO "${ctx.toSchema}"."${t}" SELECT * FROM "${ctx.fromSchema}"."${t}";`
+ *     ).join('\n')
+ *     return { sql }
+ *   },
+ *   async resetSequences(ctx) {
+ *     return { sql: `SELECT setval(pg_get_serial_sequence('${ctx.toSchema}.alunos','id'), COALESCE(MAX(id),1)) FROM "${ctx.toSchema}".alunos;` }
+ *   },
+ *   async seedFixtures(ctx) {
+ *     return { sql: `UPDATE "${ctx.toSchema}".professores SET domain='${ctx.cfDomain}' WHERE id=9901;` }
+ *   },
+ * }
+ * export default seed
+ * ```
+ */
+export interface AppSeedScript {
+    runMigrations?(ctx: AppSeedContext): Promise<AppSeedPhaseResult> | AppSeedPhaseResult;
+    copyData?(ctx: AppSeedContext): Promise<AppSeedPhaseResult> | AppSeedPhaseResult;
+    resetSequences?(ctx: AppSeedContext): Promise<AppSeedPhaseResult> | AppSeedPhaseResult;
+    seedFixtures?(ctx: AppSeedContext): Promise<AppSeedPhaseResult> | AppSeedPhaseResult;
+}
+export default class Seed extends Command {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        stage: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        apps: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'from-schema': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'to-schema': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'cf-domain': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        service: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'apps-dir': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'allow-production': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'no-wait': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        domain: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+    /**
+     * Resolve the DB service slug to seed against.
+     *
+     * If `--service` was passed, trust it. Otherwise list services and pick the
+     * single rds-postgres service registered for this stage. Fail loudly when
+     * resolution is ambiguous — never guess silently.
+     */
+    private resolveServiceSlug;
+    private printDryRun;
+}