@4ge/cli 0.1.0

package/dist/commands/template/feature/update.js

@@ -0,0 +1,82 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Flags } from '@oclif/core';
+import { BaseCommand } from '../../../base.js';
+import { updateTemplateFeature } from '../../../generated/api/sdk.gen.js';
+import { zUpdateTemplateFeatureResponse } from '../../../generated/api/zod.gen.js';
+import { validateResponse } from '../../../core/api/index.js';
+import { SuccessMessage } from '../../../ui/index.js';
+export default class TemplateFeatureUpdate extends BaseCommand {
+    static description = 'Update a feature in a template';
+    static flags = {
+        ...BaseCommand.baseFlags,
+        id: Flags.string({
+            description: 'Template ID',
+            required: true,
+        }),
+        'feature-id': Flags.string({
+            description: 'Feature ID',
+            required: true,
+        }),
+        name: Flags.string({
+            description: 'Feature name',
+        }),
+        description: Flags.string({
+            description: 'Feature description',
+        }),
+        public: Flags.boolean({
+            description: 'Whether the feature is public',
+            allowNo: true,
+        }),
+    };
+    static examples = [
+        '<%= config.bin %> template:feature:update --id <template_id> --feature-id <feature_id> --name "New Name"',
+        '<%= config.bin %> template:feature:update --id <template_id> --feature-id <feature_id> --public',
+        '<%= config.bin %> template:feature:update --id <template_id> --feature-id <feature_id> --no-public',
+    ];
+    async run() {
+        const { flags } = await this.parse(TemplateFeatureUpdate);
+        await this.renderHeader('ready', 'compact');
+        const payload = {
+            path: {
+                templateId: flags.id,
+                featureId: flags['feature-id'],
+            },
+            body: {
+                ...(flags.name !== undefined && { name: flags.name }),
+                ...(flags.description !== undefined && { description: flags.description }),
+                ...(flags.public !== undefined && { is_public: flags.public }),
+            },
+        };
+        if (this.isDryRun) {
+            await this.handleDryRun(payload);
+            return;
+        }
+        const client = await this.getClient();
+        const { data, error } = await this.withSpinner('Updating template feature...', () => updateTemplateFeature({
+            client,
+            ...payload,
+        }));
+        try {
+            const validated = validateResponse(data, error, zUpdateTemplateFeatureResponse);
+            const feature = validated.data;
+            const metadata = validated.metadata;
+            if (this.isJsonMode) {
+                this.outputJson(feature, {
+                    source: 'template feature update',
+                    templateId: flags.id,
+                    featureId: flags['feature-id'],
+                    ...metadata,
+                });
+            }
+            else {
+                await this.renderInk(_jsx(SuccessMessage, { message: `Feature "${feature.name}" (id: ${feature.id}) has been updated in template ${flags.id}.` }));
+                if (this.isInteractiveMode && metadata?.action_hints) {
+                    await this.handleActionHints(metadata.action_hints);
+                }
+            }
+        }
+        catch (err) {
+            this.handleError(`Failed to update feature ${flags['feature-id']} for template: ${flags.id}`, err);
+        }
+    }
+}

package/dist/commands/template/info.js

@@ -0,0 +1,52 @@
+import { Flags } from '@oclif/core';
+import { BaseCommand } from '../../base.js';
+import { getTemplateDetail } from '../../generated/api/sdk.gen.js';
+import { zGetTemplateDetailResponse } from '../../generated/api/zod.gen.js';
+import { validateResponse } from '../../core/api/index.js';
+export default class TemplateInfo extends BaseCommand {
+    static description = 'Get details for a specific project template';
+    static flags = {
+        ...BaseCommand.baseFlags,
+        id: Flags.string({
+            description: 'Template ID',
+            required: true,
+        }),
+    };
+    static examples = [
+        '<%= config.bin %> template:info --id <template_id>',
+        '<%= config.bin %> template:info --id <template_id> --json',
+    ];
+    async run() {
+        const { flags } = await this.parse(TemplateInfo);
+        await this.renderHeader('ready', 'compact');
+        const client = await this.getClient();
+        try {
+            const { data, error } = await this.withRetry(() => getTemplateDetail({
+                client,
+                path: { templateId: flags.id },
+            }));
+            const validated = validateResponse(data, error, zGetTemplateDetailResponse);
+            const template = validated.data;
+            const metadata = validated.metadata;
+            if (this.isJsonMode) {
+                this.outputJson(template, { source: 'template info', ...metadata });
+            }
+            else {
+                this.log(`\nTemplate: ${template.name}`);
+                this.log(`ID:       ${template.id}`);
+                this.log(`Author:   ${template.author}`);
+                this.log(`Framework: ${template.framework}`);
+                this.log(`Official:  ${template.isOfficial ? 'Yes' : 'No'}`);
+                this.log(`Features:  ${template.featuresCount}`);
+                this.log(`Created:   ${new Date(template.createdAt).toLocaleString()}`);
+                this.log(`\nDescription:\n${template.description || 'No description available.'}\n`);
+                if (this.isInteractiveMode && metadata?.action_hints) {
+                    await this.handleActionHints(metadata.action_hints);
+                }
+            }
+        }
+        catch (err) {
+            this.handleError(`Failed to fetch template detail for ID: ${flags.id}`, err);
+        }
+    }
+}

package/dist/commands/template/list.js

@@ -0,0 +1,76 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Flags } from '@oclif/core';
+import { BaseCommand } from '../../base.js';
+import { listTemplates } from '../../generated/api/sdk.gen.js';
+import { zListTemplatesResponse } from '../../generated/api/zod.gen.js';
+import { validateResponse } from '../../core/api/index.js';
+import { DataTable } from '../../ui/index.js';
+export default class TemplateList extends BaseCommand {
+    static description = 'List all available project templates';
+    static flags = {
+        ...BaseCommand.baseFlags,
+        workspace: Flags.string({
+            description: 'Filter templates by workspace ID',
+        }),
+    };
+    static examples = [
+        '<%= config.bin %> template:list',
+        '<%= config.bin %> template:list --workspace <workspace_id>',
+        '<%= config.bin %> template:list --json',
+    ];
+    async run() {
+        const { flags } = await this.parse(TemplateList);
+        await this.renderHeader('ready', 'compact');
+        const client = await this.getClient();
+        const { data, error } = await this.withRetry(() => listTemplates({ client }));
+        let templates;
+        let metadata;
+        try {
+            const validated = validateResponse(data, error, zListTemplatesResponse);
+            templates = validated.data;
+            metadata = validated.metadata;
+        }
+        catch (err) {
+            this.handleError('Failed to fetch templates', err);
+            return;
+        }
+        // Filter by workspace if flag provided (client-side)
+        const filteredTemplates = flags.workspace
+            ? templates?.filter((t) => t.workspace_id === flags.workspace) || []
+            : templates || [];
+        if (this.isJsonMode) {
+            this.outputJson(filteredTemplates, { source: 'template list', ...metadata });
+        }
+        else {
+            if (filteredTemplates.length === 0) {
+                this.log(flags.workspace ? `No templates found for workspace: ${flags.workspace}` : 'No templates found.');
+                return;
+            }
+            await this.renderInk(_jsx(DataTable, { data: filteredTemplates, columns: [
+                    { key: 'name', header: 'Name', minWidth: 20 },
+                    { key: 'id', header: 'ID' },
+                    { key: 'framework', header: 'Framework' },
+                    { key: 'author', header: 'Author' },
+                    { key: 'featuresCount', header: 'Features' },
+                    { key: 'isOfficial', header: 'Official', format: (v) => (v ? '✓' : '') },
+                ], title: "Available Templates", emptyMessage: flags.workspace ? `No templates found for workspace: ${flags.workspace}` : 'No templates found.' }));
+            if (this.isInteractiveMode) {
+                if (filteredTemplates.length > 0) {
+                    const options = filteredTemplates.map((item) => ({
+                        label: item.name || item.id,
+                        value: item.id,
+                        description: item.framework || '',
+                    }));
+                    const selectedId = await this.selectOption('Select a template for details:', options, { headerVariant: 'compact' });
+                    if (selectedId) {
+                        const { default: chalk } = await import('chalk');
+                        this.log(`\n  🚀 Run: ${chalk.cyan(`4ge template info --id ${selectedId}`)}\n`);
+                    }
+                }
+                if (metadata?.action_hints) {
+                    await this.handleActionHints(metadata.action_hints);
+                }
+            }
+        }
+    }
+}

package/dist/commands/template/pull.js

@@ -0,0 +1,99 @@
+import { BaseCommand } from '../../base.js';
+import { readConfig, getAssetPath } from '../../core/config/index.js';
+import { getTemplateDetail, getProjectDetail } from '../../generated/api/sdk.gen.js';
+import { zGetTemplateDetailResponse, zGetProjectDetailResponse } from '../../generated/api/zod.gen.js';
+import { validateResponse } from '../../core/api/index.js';
+import { SuccessMessage } from '../../ui/components/success-message.js';
+import { Flags } from '@oclif/core';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import React from 'react';
+export default class TemplatePull extends BaseCommand {
+    static description = 'Pull template data from the cloud and save it locally';
+    static flags = {
+        ...BaseCommand.baseFlags,
+        save: Flags.boolean({
+            description: 'Force saving to disk even in --json mode',
+            default: false,
+        }),
+        stdout: Flags.boolean({
+            description: 'Print to terminal without saving (human mode only)',
+            default: false,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(TemplatePull);
+        if (flags.json && flags.stdout) {
+            this.error('Cannot use --json and --stdout together');
+        }
+        if (flags.save && flags.stdout) {
+            this.error('Cannot use --stdout and --save together');
+        }
+        await this.renderHeader('ready', 'compact');
+        await this.migrateAssetsIfNeeded();
+        const client = await this.getClient();
+        const config = await readConfig();
+        const projectId = config?.project_id;
+        if (!projectId) {
+            this.handleError('Project not initialized. Run `4ge init` first.', { code: 'NOT_INITIALIZED' });
+            return;
+        }
+        // 1. Get Project Detail to find template_id
+        let templateId;
+        try {
+            const { data, error } = await this.withSpinner('Fetching project details', () => getProjectDetail({
+                client,
+                path: { projectId },
+            }));
+            const validated = validateResponse(data, error, zGetProjectDetailResponse);
+            templateId = validated.data.project_type_id ?? undefined;
+        }
+        catch (err) {
+            this.handleError('Failed to fetch project details', err);
+            return;
+        }
+        if (!templateId) {
+            this.handleError('No template associated with this project (project_type_id is null).', { code: 'NO_TEMPLATE' });
+            return;
+        }
+        // 2. Fetch Template Detail
+        let templateData;
+        try {
+            const { data, error } = await this.withSpinner('Fetching template details', () => getTemplateDetail({
+                client,
+                path: { templateId },
+            }));
+            const validated = validateResponse(data, error, zGetTemplateDetailResponse);
+            templateData = validated.data;
+        }
+        catch (err) {
+            this.handleError('Failed to fetch template details', err);
+            return;
+        }
+        const savePath = getAssetPath('template.json');
+        // 3. Output Logic
+        if (this.isJsonMode) {
+            this.outputJson(templateData);
+            if (flags.save) {
+                await this.saveToFile(savePath, templateData);
+            }
+        }
+        else if (flags.stdout) {
+            this.log(JSON.stringify(templateData, null, 2));
+        }
+        else {
+            await this.saveToFile(savePath, templateData);
+            await this.renderInk(React.createElement(SuccessMessage, { message: 'Template data saved to .4ge/assets/template.json' }));
+        }
+        if (this.isInteractiveMode) {
+            await this.handleActionHints([
+                { label: 'List template features', command: `4ge template feature list ${templateId}` },
+                { label: 'Project info', command: '4ge project info' },
+            ]);
+        }
+    }
+    async saveToFile(filePath, data) {
+        await fs.mkdir(path.dirname(filePath), { recursive: true });
+        await fs.writeFile(filePath, JSON.stringify(data, null, 2), 'utf-8');
+    }
+}

package/dist/commands/template/update.js

@@ -0,0 +1,71 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Flags } from '@oclif/core';
+import { BaseCommand } from '../../base.js';
+import { updateTemplate } from '../../generated/api/sdk.gen.js';
+import { zUpdateTemplateResponse } from '../../generated/api/zod.gen.js';
+import { validateResponse } from '../../core/api/index.js';
+import { SuccessMessage } from '../../ui/index.js';
+export default class TemplateUpdate extends BaseCommand {
+    static description = 'Update an existing project template';
+    static flags = {
+        ...BaseCommand.baseFlags,
+        id: Flags.string({
+            description: 'Template ID',
+            required: true,
+        }),
+        name: Flags.string({
+            description: 'Template name',
+        }),
+        description: Flags.string({
+            description: 'Template description',
+        }),
+        force: Flags.boolean({
+            description: 'Skip confirmation prompt',
+            default: false,
+        }),
+    };
+    static examples = [
+        '<%= config.bin %> template:update --id <template_id> --name "New Name"',
+        '<%= config.bin %> template:update --id <template_id> --description "New description"',
+    ];
+    async run() {
+        const { flags } = await this.parse(TemplateUpdate);
+        await this.renderHeader('ready', 'compact');
+        const confirmed = await this.confirmAction(`Update template ${flags.id}?`, flags.force, { headerVariant: 'compact' });
+        if (!confirmed)
+            return;
+        const payload = {
+            path: { templateId: flags.id },
+            body: {
+                ...(flags.name !== undefined && { name: flags.name }),
+                ...(flags.description !== undefined && { description: flags.description }),
+            },
+        };
+        if (this.isDryRun) {
+            await this.handleDryRun(payload);
+            return;
+        }
+        const client = await this.getClient();
+        const { data, error } = await this.withSpinner('Updating template...', () => updateTemplate({
+            client,
+            ...payload,
+        }));
+        try {
+            const validated = validateResponse(data, error, zUpdateTemplateResponse);
+            const template = validated.data;
+            const metadata = validated.metadata;
+            if (this.isJsonMode) {
+                this.outputJson(template, { source: 'template update', ...metadata });
+            }
+            else {
+                await this.renderInk(_jsx(SuccessMessage, { message: `Template "${template.name}" (id: ${template.id}) has been updated.` }));
+                if (this.isInteractiveMode && metadata?.action_hints) {
+                    await this.handleActionHints(metadata.action_hints);
+                }
+            }
+        }
+        catch (err) {
+            this.handleError(`Failed to update template: ${flags.id}`, err);
+        }
+    }
+}

package/dist/commands/whoami.js

@@ -0,0 +1,5 @@
+import AuthStatus from './auth/status.js';
+export default class Whoami extends AuthStatus {
+    static description = 'Alias for `4ge auth status`';
+    static hidden = false;
+}

package/dist/core/api/action-hints.js

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+export const ActionHintSchema = z.object({
+    description: z.string().describe('Human-readable description of the suggested action'),
+    command: z.string().describe('The 4ge CLI command to execute'),
+});
+export const ActionHintsSchema = z.array(ActionHintSchema);
+/**
+ * Parse and validate action hints from API metadata.
+ * Returns empty array if hints are missing, null, or invalid.
+ * Never throws — action hints are best-effort, not critical.
+ */
+export function parseActionHints(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const result = ActionHintsSchema.safeParse(raw);
+    return result.success ? result.data : [];
+}

package/dist/core/api/index.js

@@ -0,0 +1,3 @@
+export { validateResponse, extractData, ApiValidationError } from './validate-response.js';
+export { parseActionHints } from './action-hints.js';
+export { withRetry, computeBackoff, isRetryableResult, retryReason } from './retry.js';

package/dist/core/api/retry.js

@@ -0,0 +1,95 @@
+/**
+ * Retry helpers for transient API failures.
+ *
+ * The SDK returns `{ data?, error?, request, response }` and resolves (rather
+ * than throwing) on HTTP errors when `throwOnError` is false (the CLI default).
+ * A network failure (fetch throws) surfaces as `{ error, response: undefined }`.
+ * So retryability is decided by inspecting the resolved result.
+ */
+const DEFAULTS = {
+    baseDelayMs: 500,
+    multiplier: 2,
+    jitter: 0.25,
+};
+/**
+ * Compute the backoff delay (ms) for a given 1-based attempt number, with
+ * exponential growth and symmetric jitter.
+ *
+ * delay = base * (mult ^ (attempt-1)) * (1 ± jitter)
+ */
+export function computeBackoff(attempt, opts = {}) {
+    const base = opts.baseDelayMs ?? DEFAULTS.baseDelayMs;
+    const mult = opts.multiplier ?? DEFAULTS.multiplier;
+    const jitter = opts.jitter ?? DEFAULTS.jitter;
+    const exp = base * Math.pow(mult, attempt - 1);
+    // Symmetric jitter in [-jitter, +jitter].
+    const factor = 1 + (Math.random() * 2 - 1) * jitter;
+    return Math.max(0, Math.round(exp * factor));
+}
+/**
+ * Decide whether a resolved SDK result is a transient (retryable) failure.
+ *
+ * Retryable:
+ *   - `response` missing (network failure — fetch threw)
+ *   - HTTP 429 (Too Many Requests)
+ *   - HTTP 5xx (server errors)
+ * Not retryable:
+ *   - 4xx (except 429) — client errors, won't change on retry
+ *   - success (no error)
+ */
+export function isRetryableResult(result) {
+    if (result === null || typeof result !== 'object')
+        return false;
+    const r = result;
+    // Success path — no error, no retry.
+    if (r.error === undefined || r.error === null)
+        return false;
+    const status = r.response?.status;
+    if (status === undefined)
+        return true; // network failure (no response)
+    if (status === 429)
+        return true;
+    if (status >= 500 && status < 600)
+        return true;
+    return false;
+}
+/**
+ * Reason label for a retryable result, for reporting in metadata.
+ */
+export function retryReason(result) {
+    if (result === null || typeof result !== 'object')
+        return 'unknown';
+    const r = result;
+    const status = r.response?.status;
+    if (status === undefined)
+        return 'network_error';
+    if (status === 429)
+        return 'rate_limited';
+    return `http_${status}`;
+}
+/**
+ * Run `fn`, retrying on transient failures with exponential backoff + jitter.
+ *
+ * Returns the final result plus the list of retry attempts (empty if the first
+ * call succeeded). `fn` must resolve to an SDK-shaped result; thrown errors are
+ * NOT retried (they indicate non-transient failures or post-call validation).
+ */
+export async function withRetry(fn, opts) {
+    const sleep = opts.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const attempts = [];
+    let lastResult;
+    for (let attempt = 0;; attempt++) {
+        lastResult = await fn();
+        if (attempt >= opts.maxAttempts || !isRetryableResult(lastResult)) {
+            return { result: lastResult, attempts };
+        }
+        const delayMs = computeBackoff(attempt + 1, opts);
+        attempts.push({
+            attempt: attempt + 1,
+            status: lastResult?.response?.status,
+            reason: retryReason(lastResult),
+            delayMs,
+        });
+        await sleep(delayMs);
+    }
+}

package/dist/core/api/validate-response.js

@@ -0,0 +1,41 @@
+/**
+ * Validates an SDK response against a Zod schema at the boundary.
+ *
+ * @param sdkData - The `data` field from the SDK response (the API envelope body)
+ * @param sdkError - The `error` field from the SDK response (transport/HTTP errors)
+ * @param schema - The Zod schema for the expected API envelope shape
+ * @returns The validated API envelope with proper types
+ * @throws Error if transport error occurs or schema validation fails
+ */
+export function validateResponse(sdkData, sdkError, schema) {
+    // 1. Check for transport/HTTP-level errors
+    if (sdkError) {
+        throw new ApiValidationError('API request failed', sdkError);
+    }
+    // 2. Validate the response body against the Zod schema
+    const result = schema.safeParse(sdkData);
+    if (!result.success) {
+        throw new ApiValidationError('API response validation failed', result.error);
+    }
+    return result.data;
+}
+/**
+ * Extracts just the data payload from a validated API response.
+ * Convenience function for the common case where you only need the data field.
+ */
+export function extractData(sdkData, sdkError, schema) {
+    const validated = validateResponse(sdkData, sdkError, schema);
+    return validated.data;
+}
+/**
+ * Custom error class for API validation failures.
+ * Provides structured error info for both human and agent consumption.
+ */
+export class ApiValidationError extends Error {
+    details;
+    constructor(message, details) {
+        super(message);
+        this.name = 'ApiValidationError';
+        this.details = details;
+    }
+}