hereya-cli 0.55.0 → 0.56.0

package/dist/backend/common.d.ts

@@ -7,13 +7,17 @@ export interface Backend {
     deleteState(input: DeleteStateInput): Promise<DeleteStateOutput>;
     deleteWorkspace(input: DeleteWorkspaceInput): Promise<DeleteWorkspaceOutput>;
     exportBackend(): Promise<ExportBackendOutput>;
+    getPackageByVersion?(name: string, version: string): Promise<GetPackageOutput>;
+    getPackageLatest?(name: string): Promise<GetPackageOutput>;
     getProvisioningId(input: GetProvisioningIdInput): Promise<GetProvisioningIdOutput>;
     getState(input: GetStateInput): Promise<GetStateOutput>;
     getWorkspace(workspace: string): Promise<GetWorkspaceOutput>;
     getWorkspaceEnv(input: GetWorkspaceEnvInput): Promise<GetWorkspaceEnvOutput>;
     importBackend(input: ImportBackendInput): Promise<ImportBackendOutput>;
     init(options: InitProjectInput): Promise<InitProjectOutput>;
+    listPackageVersions?(name: string): Promise<ListPackageVersionsOutput>;
     listWorkspaces(): Promise<string[]>;
+    publishPackage?(input: PublishPackageInput): Promise<PublishPackageOutput>;
     removePackageFromWorkspace(input: RemovePackageFromWorkspaceInput): Promise<RemovePackageFromWorkspaceOutput>;
     saveState(config: Config, workspace?: string): Promise<void>;
     setEnvVar(input: SetEnvVarInput): Promise<SetEnvVarOutput>;
@@ -227,3 +231,61 @@ export type UpdateWorkspaceOutput = {
     success: true;
     workspace: Workspace;
 };
+export type PublishPackageInput = {
+    commit: string;
+    description: string;
+    doc?: string;
+    iac: string;
+    infra: string;
+    name: string;
+    onDeployPkg?: string;
+    onDeployVersion?: string;
+    repository: string;
+    sha256: string;
+    version: string;
+    visibility?: 'PRIVATE' | 'PUBLIC';
+};
+export type PublishPackageOutput = {
+    package: {
+        id: string;
+        name: string;
+        version: string;
+    };
+    success: true;
+} | {
+    reason: string;
+    success: false;
+};
+export type RegistryPackage = {
+    commit?: string;
+    createdAt?: string;
+    description: string;
+    doc?: string;
+    iac?: string;
+    id: string;
+    infra?: string;
+    name: string;
+    onDeploy?: {
+        pkg: string;
+        version: string;
+    };
+    repository?: string;
+    sha256?: string;
+    updatedAt?: string;
+    version: string;
+    visibility?: 'PRIVATE' | 'PUBLIC';
+};
+export type GetPackageOutput = {
+    package: RegistryPackage;
+    success: true;
+} | {
+    reason: string;
+    success: false;
+};
+export type ListPackageVersionsOutput = {
+    packages: RegistryPackage[];
+    success: true;
+} | {
+    reason: string;
+    success: false;
+};

package/dist/backend/file.d.ts

@@ -1,5 +1,5 @@
 import { Config } from '../lib/config/common.js';
-import { AddPackageToWorkspaceInput, AddPackageToWorkspaceOutput, Backend, CreateWorkspaceInput, CreateWorkspaceOutput, DeleteStateInput, DeleteStateOutput, DeleteWorkspaceInput, DeleteWorkspaceOutput, ExportBackendOutput, GetProvisioningIdInput, GetProvisioningIdOutput, GetStateInput, GetStateOutput, GetWorkspaceEnvInput, GetWorkspaceEnvOutput, GetWorkspaceOutput, ImportBackendInput, ImportBackendOutput, InitProjectInput, InitProjectOutput, RemovePackageFromWorkspaceInput, RemovePackageFromWorkspaceOutput, SetEnvVarInput, SetEnvVarOutput, UnsetEnvVarInput, UnsetEnvVarOutput, UpdateWorkspaceInput, UpdateWorkspaceOutput } from './common.js';
+import { AddPackageToWorkspaceInput, AddPackageToWorkspaceOutput, Backend, CreateWorkspaceInput, CreateWorkspaceOutput, DeleteStateInput, DeleteStateOutput, DeleteWorkspaceInput, DeleteWorkspaceOutput, ExportBackendOutput, GetPackageOutput, GetProvisioningIdInput, GetProvisioningIdOutput, GetStateInput, GetStateOutput, GetWorkspaceEnvInput, GetWorkspaceEnvOutput, GetWorkspaceOutput, ImportBackendInput, ImportBackendOutput, InitProjectInput, InitProjectOutput, ListPackageVersionsOutput, PublishPackageInput, PublishPackageOutput, RemovePackageFromWorkspaceInput, RemovePackageFromWorkspaceOutput, SetEnvVarInput, SetEnvVarOutput, UnsetEnvVarInput, UnsetEnvVarOutput, UpdateWorkspaceInput, UpdateWorkspaceOutput } from './common.js';
 import { FileStorage } from './file-storage/common.js';
 export declare class FileBackend implements Backend {
     private readonly fileStorage;
@@ -9,13 +9,17 @@ export declare class FileBackend implements Backend {
     deleteState(input: DeleteStateInput): Promise<DeleteStateOutput>;
     deleteWorkspace(input: DeleteWorkspaceInput): Promise<DeleteWorkspaceOutput>;
     exportBackend(): Promise<ExportBackendOutput>;
+    getPackageByVersion(_: string, __: string): Promise<GetPackageOutput>;
+    getPackageLatest(_: string): Promise<GetPackageOutput>;
     getProvisioningId(input: GetProvisioningIdInput): Promise<GetProvisioningIdOutput>;
     getState(input: GetStateInput): Promise<GetStateOutput>;
     getWorkspace(workspace: string): Promise<GetWorkspaceOutput>;
     getWorkspaceEnv(input: GetWorkspaceEnvInput): Promise<GetWorkspaceEnvOutput>;
     importBackend(_: ImportBackendInput): Promise<ImportBackendOutput>;
     init(options: InitProjectInput): Promise<InitProjectOutput>;
+    listPackageVersions(_: string): Promise<ListPackageVersionsOutput>;
     listWorkspaces(): Promise<string[]>;
+    publishPackage(_: PublishPackageInput): Promise<PublishPackageOutput>;
     removePackageFromWorkspace(input: RemovePackageFromWorkspaceInput): Promise<RemovePackageFromWorkspaceOutput>;
     saveState(config: Config, workspace?: string): Promise<void>;
     setEnvVar(input: SetEnvVarInput): Promise<SetEnvVarOutput>;

package/dist/backend/file.js

@@ -180,6 +180,18 @@ export class FileBackend {
             success: false,
         };
     }
+    async getPackageByVersion(_, __) {
+        return {
+            reason: 'Package registry operations are only supported with the cloud backend. Please run `hereya login` to use cloud backend.',
+            success: false,
+        };
+    }
+    async getPackageLatest(_) {
+        return {
+            reason: 'Package registry operations are only supported with the cloud backend. Please run `hereya login` to use cloud backend.',
+            success: false,
+        };
+    }
     async getProvisioningId(input) {
         const idPaths = [`provisioning/${input.logicalId}.yaml`, `provisioning/${input.logicalId}.yml`];
         const newId = `p-${randomUUID()}`;
@@ -331,6 +343,12 @@ export class FileBackend {
             },
         };
     }
+    async listPackageVersions(_) {
+        return {
+            reason: 'Package registry operations are only supported with the cloud backend. Please run `hereya login` to use cloud backend.',
+            success: false,
+        };
+    }
     async listWorkspaces() {
         const workspaces$ = await this.fileStorage.listFileNames({ directory: 'state/workspaces' });
         if (workspaces$.success) {
@@ -341,6 +359,12 @@ export class FileBackend {
         }
         throw new Error(`Could not list workspaces: ${workspaces$.error}`);
     }
+    async publishPackage(_) {
+        return {
+            reason: 'Package registry operations are only supported with the cloud backend. Please run `hereya login` to use cloud backend.',
+            success: false,
+        };
+    }
     async removePackageFromWorkspace(input) {
         const workspace$ = await this.getWorkspace(input.workspace);
         if (!workspace$.found) {

package/dist/commands/doc/index.d.ts

@@ -0,0 +1,17 @@
+import { Command } from '@oclif/core';
+export default class Doc extends Command {
+    static args: {
+        package: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        chdir: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'no-doc': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+    private displayMarkdown;
+    private displayPackage;
+    private parsePackageSpec;
+}

package/dist/commands/doc/index.js

@@ -0,0 +1,154 @@
+import { Args, Command, Flags } from '@oclif/core';
+import chalk from 'chalk';
+import { marked } from 'marked';
+import { markedTerminal } from 'marked-terminal';
+import { getBackend } from '../../backend/index.js';
+// Configure marked with terminal renderer
+marked.use(markedTerminal({
+    reflowText: true,
+    showSectionPrefix: false,
+    width: 80,
+}));
+export default class Doc extends Command {
+    static args = {
+        package: Args.string({
+            description: 'Package name with optional version (e.g., my-package or my-package@1.0.0)',
+            required: true,
+        }),
+    };
+    static description = 'Display documentation for a package from the registry';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> my-package',
+        '<%= config.bin %> <%= command.id %> my-package@1.0.0',
+        '<%= config.bin %> <%= command.id %> my-package --json',
+        '<%= config.bin %> <%= command.id %> my-package --no-doc',
+    ];
+    static flags = {
+        chdir: Flags.directory({
+            char: 'C',
+            default: '.',
+            description: 'directory to run command in',
+            helpGroup: 'global',
+        }),
+        json: Flags.boolean({
+            char: 'j',
+            description: 'Output in JSON format',
+        }),
+        'no-doc': Flags.boolean({
+            description: 'Show only metadata without the full documentation',
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(Doc);
+        // Change to specified directory
+        if (flags.chdir !== '.') {
+            process.chdir(flags.chdir);
+        }
+        // Parse package name and version
+        const { name, version } = this.parsePackageSpec(args.package);
+        // Get backend
+        const backend = await getBackend();
+        // Check if backend supports registry operations
+        if (!backend.getPackageLatest || !backend.getPackageByVersion) {
+            this.error('Package registry operations are only supported with the cloud backend. Please run `hereya login` to use cloud backend.');
+        }
+        try {
+            // Fetch package information
+            const result = version
+                ? await backend.getPackageByVersion(name, version)
+                : await backend.getPackageLatest(name);
+            if (!result.success) {
+                this.error(result.reason);
+            }
+            const pkg = result.package;
+            // Output JSON if requested
+            if (flags.json) {
+                this.log(JSON.stringify(pkg, null, 2));
+                return;
+            }
+            // Display package information
+            this.displayPackage(pkg, flags['no-doc']);
+        }
+        catch (error) {
+            this.error(error instanceof Error ? error.message : 'Failed to fetch package documentation');
+        }
+    }
+    displayMarkdown(content) {
+        // Render markdown for terminal display
+        const rendered = marked(content);
+        // Remove any trailing newlines to avoid extra spacing
+        this.log(rendered.trimEnd());
+    }
+    displayPackage(pkg, noDoc) {
+        // Header with package name, version, and visibility
+        const visibilityBadge = pkg.visibility === 'PUBLIC'
+            ? chalk.green('PUBLIC')
+            : chalk.yellow('PRIVATE');
+        this.log(chalk.bold.cyan(`📦 ${pkg.name}@${pkg.version}`) + ' ' + visibilityBadge);
+        this.log('━'.repeat(50));
+        // Description
+        if (pkg.description) {
+            this.log(chalk.bold('Description:') + ' ' + pkg.description);
+            this.log();
+        }
+        // Repository and commit info
+        if (pkg.repository) {
+            this.log(chalk.bold('Repository:') + ' ' + chalk.blue.underline(pkg.repository));
+        }
+        if (pkg.commit) {
+            this.log(chalk.bold('Commit:') + ' ' + chalk.gray(pkg.commit));
+        }
+        if (pkg.sha256) {
+            this.log(chalk.bold('SHA256:') + ' ' + chalk.gray(pkg.sha256.slice(0, 16) + '...'));
+        }
+        // Infrastructure details
+        if (pkg.iac || pkg.infra) {
+            this.log();
+            this.log(`${chalk.bold('Infrastructure:')} ${pkg.iac || 'Unknown'} on ${pkg.infra || 'Unknown'}`);
+        }
+        // OnDeploy hook
+        if (pkg.onDeploy) {
+            this.log();
+            this.log(`${chalk.bold('On Deploy Hook:')} ${pkg.onDeploy.pkg}@${pkg.onDeploy.version}`);
+        }
+        // Timestamps
+        if (pkg.createdAt || pkg.updatedAt) {
+            this.log();
+            if (pkg.createdAt) {
+                const created = new Date(pkg.createdAt).toLocaleString();
+                this.log(`${chalk.bold('Created:')} ${chalk.gray(created)}`);
+            }
+            if (pkg.updatedAt) {
+                const updated = new Date(pkg.updatedAt).toLocaleString();
+                this.log(`${chalk.bold('Updated:')} ${chalk.gray(updated)}`);
+            }
+        }
+        // Documentation content
+        if (!noDoc && pkg.doc) {
+            this.log();
+            this.log(chalk.bold.blue('━━━ Documentation ━━━'));
+            this.log();
+            this.displayMarkdown(pkg.doc);
+        }
+        else if (!noDoc && !pkg.doc) {
+            this.log();
+            this.log(chalk.gray('(No documentation available)'));
+        }
+    }
+    parsePackageSpec(spec) {
+        const atIndex = spec.lastIndexOf('@');
+        // Handle scoped packages like @org/package
+        if (atIndex > 0) {
+            const possibleVersion = spec.slice(atIndex + 1);
+            // Check if what comes after @ looks like a version
+            if (/^\d+\.\d+\.\d+/.test(possibleVersion)) {
+                return {
+                    name: spec.slice(0, atIndex),
+                    version: possibleVersion,
+                };
+            }
+        }
+        // No version specified
+        return { name: spec };
+    }
+}

package/dist/commands/publish/index.d.ts

@@ -0,0 +1,32 @@
+import { Command } from '@oclif/core';
+interface HereyarcConfig {
+    description: string;
+    iac: string;
+    infra: string;
+    name: string;
+    onDeploy?: {
+        pkg: string;
+        version: string;
+    };
+    version: string;
+    visibility?: 'PRIVATE' | 'private' | 'PUBLIC' | 'public';
+}
+export default class Publish extends Command {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        chdir: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    calculateGitArchiveSha256(packageDir: string): Promise<string>;
+    displayPublishError(reason: string, config: HereyarcConfig): void;
+    getGitInfo(packageDir: string): Promise<{
+        commit: string;
+        repository: string;
+        sha256: string;
+    }>;
+    loadConfig(packageDir: string): Promise<HereyarcConfig>;
+    loadReadme(packageDir: string): string | undefined;
+    run(): Promise<void>;
+    validateConfig(config: HereyarcConfig): void;
+}
+export {};

package/dist/commands/publish/index.js

@@ -0,0 +1,239 @@
+import { Command, Flags } from '@oclif/core';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { simpleGit } from 'simple-git';
+import * as yaml from 'yaml';
+import { getBackend } from '../../backend/index.js';
+export default class Publish extends Command {
+    static description = 'Publish a package to the Hereya registry';
+    static examples = [
+        '$ hereya publish',
+        '$ hereya publish --chdir=/path/to/package',
+    ];
+    static flags = {
+        chdir: Flags.string({
+            description: `
+        Directory where the command will be executed.
+        If not specified, it defaults to the current working directory.
+      `,
+            required: false,
+        }),
+    };
+    async calculateGitArchiveSha256(packageDir) {
+        const { exec } = await import('node:child_process');
+        const { promisify } = await import('node:util');
+        const execAsync = promisify(exec);
+        try {
+            // Create a tar archive of HEAD and calculate its SHA256
+            const { stdout } = await execAsync('git archive --format=tar HEAD | shasum -a 256', {
+                cwd: packageDir,
+                encoding: 'utf8',
+                maxBuffer: 50 * 1024 * 1024 // 50MB buffer for large repos
+            });
+            // The shasum output is "hash  -" so we take the first part
+            const sha256 = stdout.trim().split(' ')[0];
+            if (!sha256 || sha256.length !== 64) {
+                this.error('Failed to calculate SHA256 hash of the repository');
+            }
+            return sha256;
+        }
+        catch (error) {
+            this.error(`Failed to calculate SHA256: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    displayPublishError(reason, config) {
+        this.log('\n❌ Failed to publish package\n');
+        // Handle specific error cases with helpful messages
+        if (reason.toLowerCase().includes('already exists')) {
+            this.log(`Package ${config.name}@${config.version} already exists in the registry.`);
+            this.log('\nPossible solutions:');
+            this.log('  • Increment the version number in hereyarc.yaml');
+            this.log('  • Use a different package name');
+            this.log('  • If you own this package, delete the existing version first');
+        }
+        else if (reason.toLowerCase().includes('permission')) {
+            this.log('You do not have permission to publish this package.');
+            this.log('\nPossible reasons:');
+            this.log('  • The package namespace is owned by another user/organization');
+            this.log('  • Your account does not have publishing privileges');
+            this.log('  • Contact the namespace owner for access');
+        }
+        else if (reason.toLowerCase().includes('authentication')) {
+            this.log('Authentication failed.');
+            this.log('\nPlease run: hereya login');
+        }
+        else if (reason.includes('\n')) {
+            // Multiple validation errors
+            this.log('Validation errors:');
+            const errors = reason.split('\n');
+            for (const error of errors) {
+                this.log(`  • ${error}`);
+            }
+        }
+        else {
+            // Single error message
+            this.log(`Error: ${reason}`);
+        }
+        this.log(''); // Empty line for spacing
+        this.error('Package publication failed', { exit: 1 });
+    }
+    async getGitInfo(packageDir) {
+        const git = simpleGit(packageDir);
+        // Check if it's a git repository
+        const isRepo = await git.checkIsRepo();
+        if (!isRepo) {
+            this.error('The current directory is not a git repository');
+        }
+        // Get current commit SHA
+        const commit = await git.revparse(['HEAD']);
+        if (!commit) {
+            this.error('Could not get current commit SHA');
+        }
+        // Get repository URL
+        const remotes = await git.getRemotes(true);
+        if (remotes.length === 0) {
+            this.error('No git remotes found');
+        }
+        // Use origin remote by default, or the first one available
+        const origin = remotes.find((r) => r.name === 'origin') || remotes[0];
+        if (!origin || !origin.refs.fetch) {
+            this.error('Could not find repository URL');
+        }
+        let repository = origin.refs.fetch;
+        // Convert SSH URLs to HTTPS
+        if (repository.startsWith('git@github.com:')) {
+            repository = repository.replace('git@github.com:', 'https://github.com/');
+        }
+        // Remove .git suffix if present
+        if (repository.endsWith('.git')) {
+            repository = repository.slice(0, -4);
+        }
+        // Calculate SHA256 of the git archive
+        const sha256 = await this.calculateGitArchiveSha256(packageDir);
+        return { commit: commit.trim(), repository, sha256 };
+    }
+    async loadConfig(packageDir) {
+        // Look for hereyarc.yaml or hereyarc.yml
+        let configPath = join(packageDir, 'hereyarc.yaml');
+        if (!existsSync(configPath)) {
+            configPath = join(packageDir, 'hereyarc.yml');
+            if (!existsSync(configPath)) {
+                this.error('No hereyarc.yaml or hereyarc.yml file found in the current directory');
+            }
+        }
+        // Parse the configuration file
+        const configContent = readFileSync(configPath, 'utf8');
+        const config = yaml.parse(configContent);
+        // Validate required fields
+        this.validateConfig(config);
+        return config;
+    }
+    loadReadme(packageDir) {
+        // Check for README files in various formats
+        const readmeVariants = [
+            'README.md',
+            'readme.md',
+            'Readme.md',
+            'README.MD',
+            'README',
+            'readme',
+            'README.txt',
+            'readme.txt',
+        ];
+        for (const variant of readmeVariants) {
+            const readmePath = join(packageDir, variant);
+            if (existsSync(readmePath)) {
+                try {
+                    const content = readFileSync(readmePath, 'utf8');
+                    if (content.trim()) {
+                        this.log(`   README: Found ${variant}`);
+                        return content;
+                    }
+                }
+                catch {
+                    // Ignore read errors and try next variant
+                    continue;
+                }
+            }
+        }
+        this.log('   README: Not found (optional)');
+        return undefined;
+    }
+    async run() {
+        const { flags } = await this.parse(Publish);
+        const packageDir = flags.chdir || process.cwd();
+        try {
+            // Load and validate configuration
+            const config = await this.loadConfig(packageDir);
+            // Display package info
+            this.log(`\n📦 Preparing package ${config.name}@${config.version}`);
+            this.log(`   Description: ${config.description}`);
+            this.log(`   Infrastructure: ${config.infra} (${config.iac})`);
+            if (config.visibility) {
+                this.log(`   Visibility: ${config.visibility}`);
+            }
+            // Get git information (including SHA256 of git archive)
+            this.log('\n🔍 Analyzing repository...');
+            const gitInfo = await this.getGitInfo(packageDir);
+            const { commit, repository, sha256 } = gitInfo;
+            this.log(`   Repository: ${repository}`);
+            this.log(`   Commit: ${commit.slice(0, 8)}`);
+            this.log(`   SHA256: ${sha256.slice(0, 16)}...`);
+            // Load README content if available
+            const readmeContent = this.loadReadme(packageDir);
+            // Load backend configuration and check if it's cloud backend
+            this.log('\n🔐 Checking authentication...');
+            const backend = await getBackend();
+            if (!backend.publishPackage) {
+                this.log('\n❌ Authentication failed\n');
+                this.error('Publishing packages is only supported with the cloud backend. Please run `hereya login` first.');
+            }
+            this.log('   ✓ Authenticated with Hereya Cloud');
+            // Prepare the publish input (normalize visibility to uppercase)
+            const publishInput = {
+                commit: commit.trim(),
+                description: config.description,
+                doc: readmeContent,
+                iac: config.iac,
+                infra: config.infra,
+                name: config.name,
+                onDeployPkg: config.onDeploy?.pkg,
+                onDeployVersion: config.onDeploy?.version,
+                repository,
+                sha256,
+                version: config.version,
+                visibility: config.visibility?.toUpperCase(),
+            };
+            this.log('\n📤 Publishing to registry...');
+            // Publish the package
+            const result = await backend.publishPackage(publishInput);
+            if (!result.success) {
+                this.displayPublishError(result.reason, config);
+                return;
+            }
+            this.log(`\n✅ Successfully published ${result.package.name}@${result.package.version}`);
+            this.log(`   Package ID: ${result.package.id}`);
+            this.log('');
+        }
+        catch (error) {
+            this.error(error instanceof Error ? error.message : String(error));
+        }
+    }
+    validateConfig(config) {
+        if (!config.name) {
+            this.error('Missing required field "name" in hereyarc.yaml');
+        }
+        if (!config.version) {
+            this.error('Missing required field "version" in hereyarc.yaml');
+        }
+        if (!config.description) {
+            this.error('Missing required field "description" in hereyarc.yaml');
+        }
+        if (!config.iac) {
+            this.error('Missing required field "iac" in hereyarc.yaml');
+        }
+        if (!config.infra) {
+            this.error('Missing required field "infra" in hereyarc.yaml');
+        }
+    }
+}