@4ge/cli 0.1.0

package/dist/commands/story/pull.js

@@ -0,0 +1,125 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Flags } from '@oclif/core';
+import { BaseCommand } from '../../base.js';
+import { getCollectionDir } from '../../core/config/index.js';
+import { resolveRecursive, resolveRoadmapFilter } from '../../core/config/defaults.js';
+import { getStoryDetail, getStoryTree } from '../../generated/api/sdk.gen.js';
+import { zGetStoryTreeResponse, zGetStoryDetailResponse } from '../../generated/api/zod.gen.js';
+import { validateResponse } from '../../core/api/index.js';
+import { SuccessMessage } from '../../ui/index.js';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+export default class StoryPull extends BaseCommand {
+    static description = 'Download story details and optionally its hierarchy';
+    static examples = [
+        '<%= config.bin %> story:pull --id <uuid>',
+        '<%= config.bin %> story:pull --id <uuid> --json',
+        '<%= config.bin %> story:pull --id <uuid> --recursive',
+        '<%= config.bin %> story:pull --id <uuid> --recursive --roadmap now --status BACKLOG',
+    ];
+    static flags = {
+        ...BaseCommand.baseFlags,
+        id: Flags.string({
+            description: 'Story ID',
+            required: true,
+        }),
+        recursive: Flags.boolean({
+            description: 'Pull full hierarchy tree instead of just the story detail',
+            allowNo: true,
+        }),
+        roadmap: Flags.string({
+            description: 'Filter hierarchy by roadmap status (now|next|later). Only used with --recursive.',
+            options: ['now', 'next', 'later'],
+        }),
+        status: Flags.string({
+            description: 'Filter hierarchy by status. Only used with --recursive.',
+        }),
+        save: Flags.boolean({
+            description: 'Force save to disk even in JSON mode',
+            default: false,
+        }),
+        stdout: Flags.boolean({
+            description: 'Print to stdout without saving',
+            default: false,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(StoryPull);
+        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 projectId = await this.getProjectIdOrExit();
+        const isRecursive = resolveRecursive(flags.recursive, this.localConfig);
+        const spinnerMsg = isRecursive ? `Pulling story ${flags.id} tree...` : `Pulling story ${flags.id}...`;
+        const roadmapFilter = resolveRoadmapFilter(flags.roadmap, this.localConfig);
+        const response = await this.withSpinner(spinnerMsg, () => {
+            if (isRecursive) {
+                return getStoryTree({
+                    client,
+                    path: {
+                        projectId,
+                        storyId: flags.id,
+                    },
+                    query: {
+                        ...(roadmapFilter ? { roadmap: roadmapFilter } : {}),
+                        ...(flags.status ? { status: flags.status } : {}),
+                    },
+                });
+            }
+            else {
+                return getStoryDetail({
+                    client,
+                    path: {
+                        projectId,
+                        storyId: flags.id,
+                    },
+                });
+            }
+        });
+        const { data, error } = response;
+        try {
+            let payload;
+            let metadata;
+            if (isRecursive) {
+                // The generated tree schema models `data` as optional (the tree payload
+                // is loosely typed). Cast to the envelope type — the validation still
+                // runs and the payload is treated as `unknown`.
+                const validated = validateResponse(data, error, zGetStoryTreeResponse);
+                payload = validated.data;
+                metadata = validated.metadata;
+            }
+            else {
+                const validated = validateResponse(data, error, zGetStoryDetailResponse);
+                payload = validated.data;
+                metadata = validated.metadata;
+            }
+            const savePath = path.join(getCollectionDir('stories'), `${flags.id}.json`);
+            if (this.isJsonMode) {
+                this.outputJson(payload);
+                if (flags.save) {
+                    await this.saveToFile(savePath, payload);
+                }
+            }
+            else if (flags.stdout) {
+                this.log(JSON.stringify(payload, null, 2));
+            }
+            else {
+                await this.saveToFile(savePath, payload);
+                await this.renderInk(_jsx(SuccessMessage, { message: `Story saved to .4ge/assets/stories/${flags.id}.json` }));
+            }
+        }
+        catch (err) {
+            this.handleError(`Failed to pull story: ${flags.id}`, err);
+        }
+    }
+    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/story/show.js

@@ -0,0 +1,57 @@
+import { Flags } from '@oclif/core';
+import { BaseCommand } from '../../base.js';
+import { getStoryDetail } from '../../generated/api/sdk.gen.js';
+import { zGetStoryDetailResponse } from '../../generated/api/zod.gen.js';
+import { validateResponse } from '../../core/api/index.js';
+export default class StoryShow extends BaseCommand {
+    static description = 'Show detailed information for a specific story';
+    static examples = [
+        '<%= config.bin %> story:show --id <uuid>',
+        '<%= config.bin %> story:show --id <uuid> --json',
+    ];
+    static flags = {
+        ...BaseCommand.baseFlags,
+        id: Flags.string({
+            description: 'Story ID',
+            required: true,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(StoryShow);
+        const client = await this.getClient();
+        const projectId = await this.getProjectIdOrExit();
+        await this.renderHeader('ready', 'compact');
+        const response = await this.withSpinner(`Fetching story ${flags.id}...`, () => getStoryDetail({
+            client,
+            path: {
+                projectId,
+                storyId: flags.id
+            },
+        }));
+        const { data, error } = response;
+        try {
+            const validated = validateResponse(data, error, zGetStoryDetailResponse);
+            const payload = validated.data;
+            const metadata = validated.metadata;
+            if (this.isJsonMode) {
+                this.outputJson(payload, { source: 'story show' });
+            }
+            else {
+                this.log(`\nStory: ${payload.label}`);
+                this.log(`ID:     ${payload.id}`);
+                this.log(`Status: ${payload.status}`);
+                this.log(`Roadmap: ${payload.roadmap_status}`);
+                this.log(`Epic ID: ${payload.parent_id || 'None'}`);
+                if (payload.description) {
+                    this.log(`\nDescription:\n${payload.description}\n`);
+                }
+                if (this.isInteractiveMode && metadata?.action_hints) {
+                    await this.handleActionHints(metadata.action_hints);
+                }
+            }
+        }
+        catch (err) {
+            this.handleError(`Failed to fetch story detail for ID: ${flags.id}`, err);
+        }
+    }
+}

package/dist/commands/story/update.js

@@ -0,0 +1,103 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Flags } from '@oclif/core';
+import { BaseCommand } from '../../base.js';
+import { updateStory } from '../../generated/api/sdk.gen.js';
+import { zUpdateStoryResponse } from '../../generated/api/zod.gen.js';
+import { validateResponse } from '../../core/api/index.js';
+import { SuccessMessage } from '../../ui/index.js';
+export default class StoryUpdate extends BaseCommand {
+    static description = 'Update a story';
+    static examples = [
+        '<%= config.bin %> story:update --id <uuid> --status IN_DEVELOPMENT',
+        '<%= config.bin %> story:update --id <uuid> --status COMPLETE --title "New Title"',
+    ];
+    static flags = {
+        ...BaseCommand.baseFlags,
+        id: Flags.string({
+            description: 'Story ID (UUID)',
+            required: true,
+        }),
+        status: Flags.string({
+            description: 'New status (BACKLOG|NOT_STARTED|IN_PLANNING|READY_FOR_DEVELOPMENT|IN_DEVELOPMENT|BLOCKED|REVIEW|COMPLETE)',
+            options: ['BACKLOG', 'NOT_STARTED', 'IN_PLANNING', 'READY_FOR_DEVELOPMENT', 'IN_DEVELOPMENT', 'BLOCKED', 'REVIEW', 'COMPLETE'],
+        }),
+        title: Flags.string({
+            description: 'New title',
+        }),
+        description: Flags.string({
+            description: 'New description',
+        }),
+        priority: Flags.string({
+            description: 'New priority',
+        }),
+        'roadmap-status': Flags.string({
+            description: 'New roadmap status (now|next|later)',
+            options: ['now', 'next', 'later'],
+        }),
+        force: Flags.boolean({
+            description: 'Skip confirmation prompt',
+            default: false,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(StoryUpdate);
+        const projectId = await this.getProjectIdOrExit();
+        await this.renderHeader('ready', 'compact');
+        const body = {};
+        if (flags.status !== undefined)
+            body.status = flags.status;
+        if (flags.title !== undefined)
+            body.label = flags.title;
+        if (flags.description !== undefined)
+            body.description = flags.description;
+        if (flags.priority !== undefined)
+            body.priority = flags.priority;
+        if (flags['roadmap-status'] !== undefined)
+            body.roadmap_status = flags['roadmap-status'];
+        if (Object.keys(body).length === 0) {
+            const message = 'At least one field must be provided to update (--status, --title, --description, --priority, --roadmap-status)';
+            if (this.isJsonMode) {
+                this.outputErrorAndExit({ message, code: 'MISSING_INPUT' });
+            }
+            else {
+                this.error(message);
+            }
+        }
+        const confirmed = await this.confirmAction(`Update story ${flags.id}?`, flags.force, { headerVariant: 'compact' });
+        if (!confirmed)
+            return;
+        const payload = {
+            path: {
+                projectId,
+                storyId: flags.id,
+            },
+            body,
+        };
+        if (this.isDryRun) {
+            await this.handleDryRun(payload);
+            return;
+        }
+        const client = await this.getClient();
+        const { data, error } = await this.withSpinner(`Updating story ${flags.id}...`, () => updateStory({
+            client,
+            ...payload,
+        }));
+        try {
+            const validated = validateResponse(data, error, zUpdateStoryResponse);
+            const story = validated.data;
+            const metadata = validated.metadata;
+            if (this.isJsonMode) {
+                this.outputJson(story, { source: 'story update', ...metadata });
+            }
+            else {
+                await this.renderInk(_jsx(SuccessMessage, { message: `Story ${flags.id} updated successfully!` }));
+                if (this.isInteractiveMode && metadata?.action_hints) {
+                    await this.handleActionHints(metadata.action_hints);
+                }
+            }
+        }
+        catch (err) {
+            this.handleError(`Failed to update story: ${flags.id}`, err);
+        }
+    }
+}

package/dist/commands/template/create.js

@@ -0,0 +1,72 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Flags } from '@oclif/core';
+import { BaseCommand } from '../../base.js';
+import { createTemplate } from '../../generated/api/sdk.gen.js';
+import { zCreateTemplateResponse } from '../../generated/api/zod.gen.js';
+import { validateResponse } from '../../core/api/index.js';
+import { SuccessMessage } from '../../ui/index.js';
+export default class TemplateCreate extends BaseCommand {
+    static description = 'Create a new project template';
+    static flags = {
+        ...BaseCommand.baseFlags,
+        name: Flags.string({
+            description: 'Template name',
+            required: true,
+        }),
+        'workspace-id': Flags.string({
+            description: 'Workspace ID',
+            required: true,
+        }),
+        description: Flags.string({
+            description: 'Template description',
+        }),
+        force: Flags.boolean({
+            description: 'Skip confirmation prompt',
+            default: false,
+        }),
+    };
+    static examples = [
+        '<%= config.bin %> template:create --name "My Template" --workspace-id <workspace_id>',
+        '<%= config.bin %> template:create --name "My Template" --workspace-id <workspace_id> --description "A great template"',
+    ];
+    async run() {
+        const { flags } = await this.parse(TemplateCreate);
+        await this.renderHeader('ready', 'compact');
+        const confirmed = await this.confirmAction(`Create new template "${flags.name}"?`, flags.force, { headerVariant: 'compact' });
+        if (!confirmed)
+            return;
+        const payload = {
+            body: {
+                name: flags.name,
+                workspace_id: flags['workspace-id'],
+                description: flags.description,
+            },
+        };
+        if (this.isDryRun) {
+            await this.handleDryRun(payload);
+            return;
+        }
+        const client = await this.getClient();
+        const { data, error } = await this.withSpinner('Creating template...', () => createTemplate({
+            client,
+            ...payload,
+        }));
+        try {
+            const validated = validateResponse(data, error, zCreateTemplateResponse);
+            const template = validated.data;
+            const metadata = validated.metadata;
+            if (this.isJsonMode) {
+                this.outputJson(template, { source: 'template create', ...metadata });
+            }
+            else {
+                await this.renderInk(_jsx(SuccessMessage, { message: `Template "${template.name}" (id: ${template.id}) has been created successfully.` }));
+                if (this.isInteractiveMode && metadata?.action_hints) {
+                    await this.handleActionHints(metadata.action_hints);
+                }
+            }
+        }
+        catch (err) {
+            this.handleError('Failed to create template', err);
+        }
+    }
+}

package/dist/commands/template/delete.js

@@ -0,0 +1,62 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Flags } from '@oclif/core';
+import { BaseCommand } from '../../base.js';
+import { deleteTemplate } from '../../generated/api/sdk.gen.js';
+import { zDeleteTemplateResponse } from '../../generated/api/zod.gen.js';
+import { validateResponse } from '../../core/api/index.js';
+import { SuccessMessage } from '../../ui/index.js';
+export default class TemplateDelete extends BaseCommand {
+    static description = 'Delete a project template';
+    static flags = {
+        ...BaseCommand.baseFlags,
+        id: Flags.string({
+            description: 'Template ID',
+            required: true,
+        }),
+        force: Flags.boolean({
+            description: 'Skip confirmation prompt',
+            char: 'f',
+        }),
+    };
+    static examples = [
+        '<%= config.bin %> template:delete --id <template_id>',
+        '<%= config.bin %> template:delete --id <template_id> --force',
+    ];
+    async run() {
+        const { flags } = await this.parse(TemplateDelete);
+        await this.renderHeader('ready', 'compact');
+        if (!(await this.confirmAction(`Delete template ${flags.id}? This cannot be undone.`, flags.force, { headerVariant: 'compact' }))) {
+            return;
+        }
+        const payload = {
+            path: { templateId: flags.id },
+        };
+        if (this.isDryRun) {
+            await this.handleDryRun(payload);
+            return;
+        }
+        const client = await this.getClient();
+        const { data, error } = await this.withSpinner('Deleting template...', () => deleteTemplate({
+            client,
+            ...payload,
+        }));
+        let metadata;
+        try {
+            const validated = validateResponse(data, error, zDeleteTemplateResponse);
+            metadata = validated.metadata;
+        }
+        catch (err) {
+            this.handleError(`Failed to delete template: ${flags.id}`, err);
+            return;
+        }
+        if (this.isJsonMode) {
+            this.outputJson({ success: true }, { source: 'template delete', id: flags.id, ...metadata });
+        }
+        else {
+            await this.renderInk(_jsx(SuccessMessage, { message: `Template ${flags.id} has been deleted.` }));
+            if (this.isInteractiveMode && metadata?.action_hints) {
+                await this.handleActionHints(metadata.action_hints);
+            }
+        }
+    }
+}

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

@@ -0,0 +1,70 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Flags } from '@oclif/core';
+import { BaseCommand } from '../../../base.js';
+import { createTemplateFeature } from '../../../generated/api/sdk.gen.js';
+import { zCreateTemplateFeatureResponse } from '../../../generated/api/zod.gen.js';
+import { validateResponse } from '../../../core/api/index.js';
+import { SuccessMessage } from '../../../ui/index.js';
+export default class TemplateFeatureCreate extends BaseCommand {
+    static description = 'Create a feature for a template';
+    static flags = {
+        ...BaseCommand.baseFlags,
+        id: Flags.string({
+            description: 'Template ID',
+            required: true,
+        }),
+        name: Flags.string({
+            description: 'Feature name',
+            required: true,
+        }),
+        description: Flags.string({
+            description: 'Feature description',
+        }),
+        public: Flags.boolean({
+            description: 'Whether the feature is public',
+            default: false,
+        }),
+    };
+    static examples = [
+        '<%= config.bin %> template:feature:create --id <template_id> --name "Authentication"',
+        '<%= config.bin %> template:feature:create --id <template_id> --name "Auth" --description "Auth feature" --public',
+    ];
+    async run() {
+        const { flags } = await this.parse(TemplateFeatureCreate);
+        await this.renderHeader('ready', 'compact');
+        const payload = {
+            path: { templateId: flags.id },
+            body: {
+                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('Creating template feature...', () => createTemplateFeature({
+            client,
+            ...payload,
+        }));
+        try {
+            const validated = validateResponse(data, error, zCreateTemplateFeatureResponse);
+            const feature = validated.data;
+            const metadata = validated.metadata;
+            if (this.isJsonMode) {
+                this.outputJson(feature, { source: 'template feature create', templateId: flags.id, ...metadata });
+            }
+            else {
+                await this.renderInk(_jsx(SuccessMessage, { message: `Feature "${feature.name}" (id: ${feature.id}) has been created for template ${flags.id}.` }));
+                if (this.isInteractiveMode && metadata?.action_hints) {
+                    await this.handleActionHints(metadata.action_hints);
+                }
+            }
+        }
+        catch (err) {
+            this.handleError(`Failed to create feature for template: ${flags.id}`, err);
+        }
+    }
+}

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

@@ -0,0 +1,75 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Flags } from '@oclif/core';
+import { BaseCommand } from '../../../base.js';
+import { deleteTemplateFeature } from '../../../generated/api/sdk.gen.js';
+import { zDeleteTemplateFeatureResponse } from '../../../generated/api/zod.gen.js';
+import { validateResponse } from '../../../core/api/index.js';
+import { SuccessMessage } from '../../../ui/index.js';
+export default class TemplateFeatureDelete extends BaseCommand {
+    static description = 'Delete a feature from a template';
+    static flags = {
+        ...BaseCommand.baseFlags,
+        id: Flags.string({
+            description: 'Template ID',
+            required: true,
+        }),
+        'feature-id': Flags.string({
+            description: 'Feature ID',
+            required: true,
+        }),
+        force: Flags.boolean({
+            description: 'Skip confirmation prompt',
+            char: 'f',
+        }),
+    };
+    static examples = [
+        '<%= config.bin %> template:feature:delete --id <template_id> --feature-id <feature_id>',
+        '<%= config.bin %> template:feature:delete --id <template_id> --feature-id <feature_id> --force',
+    ];
+    async run() {
+        await this.renderHeader('ready', 'compact');
+        const { flags } = await this.parse(TemplateFeatureDelete);
+        const message = `Delete feature ${flags['feature-id']} from template ${flags.id}? This cannot be undone.`;
+        if (!(await this.confirmAction(message, flags.force, { headerVariant: 'compact' }))) {
+            return;
+        }
+        const payload = {
+            path: {
+                templateId: flags.id,
+                featureId: flags['feature-id'],
+            },
+        };
+        if (this.isDryRun) {
+            await this.handleDryRun(payload);
+            return;
+        }
+        const client = await this.getClient();
+        const { data, error } = await this.withSpinner('Deleting template feature...', () => deleteTemplateFeature({
+            client,
+            ...payload,
+        }));
+        let metadata;
+        try {
+            const validated = validateResponse(data, error, zDeleteTemplateFeatureResponse);
+            metadata = validated.metadata;
+        }
+        catch (err) {
+            this.handleError(`Failed to delete feature ${flags['feature-id']} from template: ${flags.id}`, err);
+            return;
+        }
+        if (this.isJsonMode) {
+            this.outputJson({ success: true }, {
+                source: 'template feature delete',
+                templateId: flags.id,
+                featureId: flags['feature-id'],
+                ...metadata,
+            });
+        }
+        else {
+            await this.renderInk(_jsx(SuccessMessage, { message: `Feature ${flags['feature-id']} has been deleted from template ${flags.id}.` }));
+            if (this.isInteractiveMode && metadata?.action_hints) {
+                await this.handleActionHints(metadata.action_hints);
+            }
+        }
+    }
+}

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

@@ -0,0 +1,69 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+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';
+import { DataTable } from '../../../ui/index.js';
+export default class TemplateFeatureList extends BaseCommand {
+    static description = 'List features for a specific project template';
+    static flags = {
+        ...BaseCommand.baseFlags,
+        id: Flags.string({
+            description: 'Template ID',
+            required: true,
+        }),
+    };
+    static examples = [
+        '<%= config.bin %> template:feature:list --id <template_id>',
+        '<%= config.bin %> template:feature:list --id <template_id> --json',
+    ];
+    async run() {
+        const { flags } = await this.parse(TemplateFeatureList);
+        await this.renderHeader('ready', 'compact');
+        const client = await this.getClient();
+        let template;
+        try {
+            const { data, error } = await getTemplateDetail({
+                client,
+                path: { templateId: flags.id },
+            });
+            // NOTE: the generated zGetTemplateDetailResponse schema does not model a
+            // `features` array, and Zod strips unknown keys by default. We need the
+            // raw `features` from the envelope, so capture it from the unvalidated
+            // payload before validateResponse runs.
+            const rawFeatures = data?.data?.features;
+            const validated = validateResponse(data, error, zGetTemplateDetailResponse);
+            template = { ...validated.data, features: rawFeatures };
+        }
+        catch (err) {
+            const message = `Failed to fetch features for template: ${flags.id}`;
+            if (this.isJsonMode) {
+                this.outputErrorAndExit({ message, code: 'API_ERROR', details: err });
+            }
+            else {
+                this.error(`${message}: ${err.message || 'Unknown error'}`);
+            }
+            return;
+        }
+        const features = template.features || [];
+        if (this.isJsonMode) {
+            this.outputJson(features, {
+                source: 'template feature list',
+                templateId: flags.id,
+            });
+        }
+        else {
+            if (features.length === 0) {
+                this.log(`No features found for template: ${template.name}`);
+                return;
+            }
+            await this.renderInk(_jsx(DataTable, { data: features, columns: [
+                    { key: 'name', header: 'Name', minWidth: 20 },
+                    { key: 'id', header: 'ID' },
+                    { key: 'description', header: 'Description' },
+                    { key: 'is_public', header: 'Public', format: (v) => (v ? '✓' : '') },
+                ], title: `Features for template: ${template.name}`, emptyMessage: `No features found for template: ${template.name}` }));
+        }
+    }
+}