@fireberry/cli 0.0.5-beta.13 → 0.0.5-beta.16

package/CLAUDE.md

@@ -0,0 +1,119 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+`@fireberry/cli` is a command-line tool for managing Fireberry applications. It allows developers to initialize credentials, create new apps from templates, push components to the Fireberry platform, and install apps on Fireberry accounts.
+
+## Development Commands
+
+### Build and Development
+```bash
+npm run build          # Compile TypeScript to dist/
+npm run build:dev      # Clean, build, link globally, and make executable
+npm run dev            # Watch mode compilation
+npm run clean          # Remove dist/ directory
+```
+
+### Testing
+```bash
+npm test              # Run smoke test (verifies CLI --help works)
+```
+
+### Local Development
+```bash
+npm run build:dev     # Build and link CLI locally
+fireberry --help      # Test the linked CLI
+```
+
+### Publishing
+```bash
+npm run publish:beta  # Version bump (beta) and publish to npm with beta tag
+npm run publish:prod  # Publish to npm with latest tag
+```
+
+## Architecture
+
+### Module System
+- **Type**: ESM (ES Modules) with `"type": "module"` in package.json
+- **Module Resolution**: NodeNext
+- **Import Extensions**: All local imports must use `.js` extension (e.g., `import { foo } from "./bar.js"`)
+- **JSON Imports**: Use `with { type: "json" }` syntax (e.g., `import packageJson from "../../package.json" with { type: "json" }`)
+
+### CLI Entry Point
+- **Binary**: [dist/bin/fireberry.js](dist/bin/fireberry.js) (generated from [src/bin/fireberry.ts](src/bin/fireberry.ts))
+- **Framework**: Commander.js for command parsing and routing
+- **Error Handling**: Global error handler in [src/bin/fireberry.ts](src/bin/fireberry.ts) catches and formats errors
+
+### Command Structure
+Each CLI command is in [src/commands/](src/commands/):
+- **init**: Stores Fireberry API token in local config using `env-paths`
+- **create**: Creates new Fireberry app from templates with generated UUIDs
+- **push**: Validates manifest, zips components, uploads to Fireberry API
+- **install**: Installs app on user's Fireberry account
+
+### Configuration System
+- **User Config**: Stored via `env-paths` ("Fireberry CLI") in OS-specific config directory
+- **Config File**: `config.json` with `{ apiToken, createdAt }`
+- **Environment**: [src/config/env.ts](src/config/env.ts) loads `.env` file from project root using dotenv
+
+### API Layer ([src/api/](src/api/))
+- **axios.ts**: Axios instance with automatic token injection via interceptors
+- **API URL Logic**:
+  - Beta versions (version contains "beta") → Uses `FIREBERRY_STAGING_URL` environment variable
+  - Production versions → `FIREBERRY_API_URL` or `https://api.fireberry.com/api/v3`
+- **Authentication**: Token passed via `tokenId` header (read from config in interceptor)
+- **requests.ts**: API endpoints (`createApp`, `pushComponents`, `installApp`)
+- **types.ts**: TypeScript interfaces for API requests/responses
+
+### Component System
+Component utilities in [src/utils/components.utils.ts](src/utils/components.utils.ts):
+- **Manifest Parsing**: YAML manifest loaded from `manifest.yml` in current directory
+- **Component Validation**: Checks paths exist, components are unique
+- **Component Zipping**: Creates tar.gz archives of component builds (directories or single files)
+- **Manifest Structure**:
+  ```yaml
+  app:
+    id: "uuid"
+    name: "App Name"
+  components:
+    - type: record
+      title: component-name
+      id: "uuid"
+      path: relative/path/to/build
+      settings: {...}
+  ```
+
+### Templates ([src/templates/](src/templates/))
+Templates use mustache-style placeholders (`{{appName}}`, `{{appId}}`, `{{componentId}}`):
+- **manifest.yml**: Default manifest with single component
+- **index.html**: Basic HTML template
+
+## Key Patterns
+
+### Error Handling
+- Commands throw errors which are caught by the global handler in [src/bin/fireberry.ts:47](src/bin/fireberry.ts#L47)
+- Errors are formatted with chalk.red and prefixed with "Error:" if not already present
+- API errors map HTTP status codes to user-friendly messages
+
+### User Feedback
+- Use `ora` spinners for long-running operations (start → succeed/fail)
+- Use `chalk` for colored output (cyan for highlights, gray for details, yellow for warnings)
+- Use `inquirer` for interactive prompts when arguments are missing
+
+### File Operations
+- Use `fs-extra` for all file operations (promisified, ensures directories exist)
+- Check `fs.pathExists()` before operations
+- Use `process.cwd()` as base for relative paths in user projects
+
+### Component Path Resolution
+Component paths in manifest.yml are relative to the current working directory, not the CLI installation directory. Example: `path: static/comp/build` resolves to `process.cwd() + "/static/comp/build"`.
+
+## Important Notes
+
+- **Manifest Required**: `push` and `install` commands must be run from a directory containing `manifest.yml`
+- **Token Required**: Most commands require prior `init` to store API token
+- **Component IDs**: Must be unique UUIDs within a manifest
+- **Build Zipping**: Single files are wrapped in a directory before tar.gz creation
+- **Template Location**: Templates are resolved from `src/templates/` at compile time, copied to `dist/templates/`

package/dist/api/requests.d.ts

@@ -3,3 +3,4 @@ import type { CreateAppRequest, Manifest, ZippedComponent } from "./types.js";
 export declare const createApp: (data: CreateAppRequest) => Promise<void>;
 export declare const pushComponents: (appId: string, components: ZippedComponent[]) => Promise<void>;
 export declare const installApp: (manifest: Manifest) => Promise<void>;
+export declare const deleteApp: (manifest: Manifest) => Promise<void>;

package/dist/api/requests.js

@@ -27,3 +27,12 @@ export const installApp = async (manifest) => {
         throw new Error(error instanceof Error ? error.message : "Unknown error");
     }
 };
+export const deleteApp = async (manifest) => {
+    const url = `/services/developer/delete`;
+    try {
+        await api.delete(url, manifest);
+    }
+    catch (error) {
+        throw new Error(error instanceof Error ? error.message : "Unknown error");
+    }
+};

package/dist/api/types.d.ts

@@ -1,3 +1,4 @@
+import { COMPONENT_TYPE } from "../constants/component-types.js";
 export interface CreateAppRequest {
     appId: string;
 }
@@ -16,7 +17,30 @@ interface ManifestApp {
     name: string;
     description?: string;
 }
-export interface ManifestComponent {
+export interface RecordComponentSettings {
+    iconName: string;
+    iconColor: string;
+    objectType: number;
+}
+export interface GlobalMenuComponentSettings {
+    displayName: string;
+}
+export type ComponentSettings = RecordComponentSettings | GlobalMenuComponentSettings;
+export interface BaseManifestComponent {
+    title: string;
+    id: string;
+    path: string;
+}
+export interface RecordComponent extends BaseManifestComponent {
+    type: typeof COMPONENT_TYPE.RECORD;
+    settings: RecordComponentSettings;
+}
+export interface GlobalMenuComponent extends BaseManifestComponent {
+    type: typeof COMPONENT_TYPE.GLOBAL_MENU;
+    settings: GlobalMenuComponentSettings;
+}
+export type ManifestComponent = RecordComponent | GlobalMenuComponent;
+export interface UntypedManifestComponent {
     type: string;
     title: string;
     id: string;

package/dist/bin/fireberry.js

@@ -6,6 +6,7 @@ import { runCreate } from "../commands/create.js";
 import packageJson from "../../package.json" with { type: "json" };
 import { runPush } from "../commands/push.js";
 import { runInstall } from "../commands/install.js";
+import { runDelete } from "../commands/delete.js";
 const program = new Command();
 program
     .name("fireberry")
@@ -37,6 +38,12 @@ program.command("install")
     .action(async () => {
     await runInstall();
 });
+program
+    .command("delete")
+    .description("Delete a Fireberry app")
+    .action(async () => {
+    await runDelete();
+});
 program.parseAsync(process.argv).catch((err) => {
     const errorMessage = err instanceof Error
         ? err.message

package/dist/commands/delete.d.ts

@@ -0,0 +1 @@
+export declare function runDelete(): Promise<void>;

package/dist/commands/delete.js

@@ -0,0 +1,31 @@
+import ora from "ora";
+import chalk from "chalk";
+import inquirer from "inquirer";
+import { deleteApp } from "../api/requests.js";
+import { getManifest } from "../utils/components.utils.js";
+export async function runDelete() {
+    const spinner = ora("Loading manifest...").start();
+    try {
+        const manifest = await getManifest();
+        spinner.stop();
+        const confirmAnswer = await inquirer.prompt([
+            {
+                type: "confirm",
+                name: "confirm",
+                message: `Are you sure you want to delete app ${chalk.yellow(manifest.app.name)} (${chalk.gray(manifest.app.id)})? This action cannot be undone.`,
+                default: false,
+            },
+        ]);
+        if (!confirmAnswer.confirm) {
+            console.log(chalk.gray("Delete operation cancelled."));
+            return;
+        }
+        spinner.start(`Deleting app "${chalk.cyan(manifest.app.name)}"...`);
+        await deleteApp(manifest);
+        spinner.succeed(`Successfully deleted app "${chalk.cyan(manifest.app.name)}"`);
+    }
+    catch (error) {
+        spinner.fail("Failed to delete app");
+        throw error;
+    }
+}

package/dist/constants/component-types.d.ts

@@ -0,0 +1,5 @@
+export declare const COMPONENT_TYPE: {
+    readonly RECORD: "record";
+    readonly GLOBAL_MENU: "global-menu";
+};
+export type ComponentType = (typeof COMPONENT_TYPE)[keyof typeof COMPONENT_TYPE];

package/dist/constants/component-types.js

@@ -0,0 +1,4 @@
+export const COMPONENT_TYPE = {
+    RECORD: "record",
+    GLOBAL_MENU: "global-menu",
+};

package/dist/utils/components.utils.d.ts

@@ -1,6 +1,6 @@
-import { Manifest, ManifestComponent, ZippedComponent } from "../api/types.js";
+import { Manifest, ZippedComponent, UntypedManifestComponent } from "../api/types.js";
 export declare const getManifest: () => Promise<Manifest>;
-export declare const validateComponentBuild: (componentPath: string, comp: ManifestComponent) => Promise<void>;
+export declare const validateComponentBuild: (componentPath: string, comp: UntypedManifestComponent) => Promise<void>;
 export declare const zipComponentBuild: (componentPath: string, title: string) => Promise<Buffer>;
 export declare const validateManifestComponents: (manifest: Manifest) => Promise<void>;
 export declare const handleComponents: (manifest: Manifest) => Promise<ZippedComponent[]>;

package/dist/utils/components.utils.js

@@ -4,6 +4,7 @@ import yaml from "js-yaml";
 import chalk from "chalk";
 import * as tar from "tar";
 import os from "node:os";
+import { COMPONENT_TYPE } from "../constants/component-types.js";
 export const getManifest = async () => {
     const manifestPath = path.join(process.cwd(), "manifest.yml");
     if (!(await fs.pathExists(manifestPath))) {
@@ -20,6 +21,55 @@ export const getManifest = async () => {
     }
     return manifest;
 };
+const validateRecordComponentSettings = (comp) => {
+    const settings = comp.settings;
+    if (!settings) {
+        throw new Error(`Component "${comp.title}" (type: ${COMPONENT_TYPE.RECORD}) is missing required settings`);
+    }
+    const requiredFields = [
+        "iconName",
+        "iconColor",
+        "objectType",
+    ];
+    for (const fieldName of requiredFields) {
+        if (settings[fieldName] === undefined || settings[fieldName] === null) {
+            throw new Error(`Component "${comp.title}" (type: ${COMPONENT_TYPE.RECORD}) is missing required setting: ${fieldName}`);
+        }
+    }
+    if (typeof settings.iconName !== "string") {
+        throw new Error(`Component "${comp.title}" (type: ${COMPONENT_TYPE.RECORD}) setting "iconName" must be a string`);
+    }
+    if (typeof settings.iconColor !== "string") {
+        throw new Error(`Component "${comp.title}" (type: ${COMPONENT_TYPE.RECORD}) setting "iconColor" must be a string`);
+    }
+    if (typeof settings.objectType !== "number") {
+        throw new Error(`Component "${comp.title}" (type: ${COMPONENT_TYPE.RECORD}) setting "objectType" must be a number`);
+    }
+};
+const validateGlobalMenuComponentSettings = (comp) => {
+    const settings = comp.settings;
+    if (!settings) {
+        throw new Error(`Component "${comp.title}" (type: ${COMPONENT_TYPE.GLOBAL_MENU}) is missing required settings`);
+    }
+    if (!settings.displayName) {
+        throw new Error(`Component "${comp.title}" (type: ${COMPONENT_TYPE.GLOBAL_MENU}) is missing required setting: displayName`);
+    }
+    if (typeof settings.displayName !== "string") {
+        throw new Error(`Component "${comp.title}" (type: ${COMPONENT_TYPE.GLOBAL_MENU}) setting "displayName" must be a string`);
+    }
+};
+const validateComponentSettings = (comp) => {
+    switch (comp.type) {
+        case COMPONENT_TYPE.RECORD:
+            validateRecordComponentSettings(comp);
+            break;
+        case COMPONENT_TYPE.GLOBAL_MENU:
+            validateGlobalMenuComponentSettings(comp);
+            break;
+        default:
+            throw new Error(`Component "${comp.title}" has unsupported type: ${comp.type}. Supported types: ${COMPONENT_TYPE.RECORD}, ${COMPONENT_TYPE.GLOBAL_MENU}`);
+    }
+};
 export const validateComponentBuild = async (componentPath, comp) => {
     if (!(await fs.pathExists(componentPath))) {
         throw new Error(`Component "${comp.title}" path does not exist: ${chalk.yellow(componentPath)}\n` + `Make sure the path in manifest.yml is correct.`);
@@ -31,6 +81,7 @@ export const validateComponentBuild = async (componentPath, comp) => {
             throw new Error(`Component <${comp.id}> at: /${comp.path} not found`);
         }
     }
+    validateComponentSettings(comp);
 };
 export const zipComponentBuild = async (componentPath, title) => {
     const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "fireberry-"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fireberry/cli",
-  "version": "0.0.5-beta.13",
+  "version": "0.0.5-beta.16",
   "description": "Fireberry CLI tool",
   "type": "module",
   "author": "",

package/src/api/requests.ts

@@ -31,3 +31,12 @@ export const installApp = async (manifest: Manifest): Promise<void> => {
     throw new Error(error instanceof Error ? error.message : "Unknown error");
   }
 };
+
+export const deleteApp = async (manifest: Manifest): Promise<void> => {
+  const url = `/services/developer/delete`;
+  try {
+    await api.delete<void>(url, manifest);
+  } catch (error) {
+    throw new Error(error instanceof Error ? error.message : "Unknown error");
+  }
+};

package/src/api/types.ts

@@ -1,3 +1,5 @@
+import { COMPONENT_TYPE } from "../constants/component-types.js";
+
 export interface CreateAppRequest {
   appId: string;
 }
@@ -20,7 +22,39 @@ interface ManifestApp {
   description?: string;
 }
 
-export interface ManifestComponent {
+export interface RecordComponentSettings {
+  iconName: string;
+  iconColor: string;
+  objectType: number;
+}
+
+export interface GlobalMenuComponentSettings {
+  displayName: string;
+}
+
+export type ComponentSettings =
+  | RecordComponentSettings
+  | GlobalMenuComponentSettings;
+
+export interface BaseManifestComponent {
+  title: string;
+  id: string;
+  path: string;
+}
+
+export interface RecordComponent extends BaseManifestComponent {
+  type: typeof COMPONENT_TYPE.RECORD;
+  settings: RecordComponentSettings;
+}
+
+export interface GlobalMenuComponent extends BaseManifestComponent {
+  type: typeof COMPONENT_TYPE.GLOBAL_MENU;
+  settings: GlobalMenuComponentSettings;
+}
+
+export type ManifestComponent = RecordComponent | GlobalMenuComponent;
+
+export interface UntypedManifestComponent {
   type: string;
   title: string;
   id: string;

package/src/bin/fireberry.ts

@@ -6,6 +6,7 @@ import { runCreate } from "../commands/create.js";
 import packageJson from "../../package.json" with { type: "json" };
 import { runPush } from "../commands/push.js";
 import { runInstall } from "../commands/install.js";
+import { runDelete } from "../commands/delete.js";
 
 const program = new Command();
 
@@ -38,12 +39,19 @@ program
     await runPush();
   });
 
-  program.command("install")
+program.command("install")
     .description("Install app on your Fireberry account")
     .action(async () => {
       await runInstall();
     });
 
+program
+  .command("delete")
+  .description("Delete a Fireberry app")
+  .action(async () => {
+    await runDelete();
+  });
+
 program.parseAsync(process.argv).catch((err: unknown) => {
   const errorMessage = err instanceof Error 
     ? err.message

package/src/commands/delete.ts

@@ -0,0 +1,40 @@
+import ora from "ora";
+import chalk from "chalk";
+import inquirer from "inquirer";
+import { deleteApp } from "../api/requests.js";
+import { getManifest } from "../utils/components.utils.js";
+
+export async function runDelete(): Promise<void> {
+  const spinner = ora("Loading manifest...").start();
+
+  try {
+    const manifest = await getManifest();
+    spinner.stop();
+
+    const confirmAnswer = await inquirer.prompt([
+      {
+        type: "confirm",
+        name: "confirm",
+        message: `Are you sure you want to delete app ${chalk.yellow(
+          manifest.app.name
+        )} (${chalk.gray(manifest.app.id)})? This action cannot be undone.`,
+        default: false,
+      },
+    ]);
+
+    if (!confirmAnswer.confirm) {
+      console.log(chalk.gray("Delete operation cancelled."));
+      return;
+    }
+
+    spinner.start(`Deleting app "${chalk.cyan(manifest.app.name)}"...`);
+
+    await deleteApp(manifest);
+    spinner.succeed(
+      `Successfully deleted app "${chalk.cyan(manifest.app.name)}"`
+    );
+  } catch (error) {
+    spinner.fail("Failed to delete app");
+    throw error;
+  }
+}

package/src/constants/component-types.ts

@@ -0,0 +1,6 @@
+export const COMPONENT_TYPE = {
+  RECORD: "record",
+  GLOBAL_MENU: "global-menu",
+} as const;
+
+export type ComponentType = (typeof COMPONENT_TYPE)[keyof typeof COMPONENT_TYPE];

package/src/utils/components.utils.ts

@@ -4,7 +4,14 @@ import yaml from "js-yaml";
 import chalk from "chalk";
 import * as tar from "tar";
 import os from "node:os";
-import { Manifest, ManifestComponent, ZippedComponent } from "../api/types.js";
+import {
+  Manifest,
+  ZippedComponent,
+  UntypedManifestComponent,
+  RecordComponentSettings,
+  GlobalMenuComponentSettings,
+} from "../api/types.js";
+import { COMPONENT_TYPE } from "../constants/component-types.js";
 
 export const getManifest = async (): Promise<Manifest> => {
   const manifestPath = path.join(process.cwd(), "manifest.yml");
@@ -33,9 +40,96 @@ export const getManifest = async (): Promise<Manifest> => {
   return manifest;
 };
 
+const validateRecordComponentSettings = (
+  comp: UntypedManifestComponent
+): void => {
+  const settings = comp.settings as
+    | Partial<RecordComponentSettings>
+    | undefined;
+
+  if (!settings) {
+    throw new Error(
+      `Component "${comp.title}" (type: ${COMPONENT_TYPE.RECORD}) is missing required settings`
+    );
+  }
+
+  const requiredFields: (keyof RecordComponentSettings)[] = [
+    "iconName",
+    "iconColor",
+    "objectType",
+  ];
+
+  for (const fieldName of requiredFields) {
+    if (settings[fieldName] === undefined || settings[fieldName] === null) {
+      throw new Error(
+        `Component "${comp.title}" (type: ${COMPONENT_TYPE.RECORD}) is missing required setting: ${fieldName}`
+      );
+    }
+  }
+
+  if (typeof settings.iconName !== "string") {
+    throw new Error(
+      `Component "${comp.title}" (type: ${COMPONENT_TYPE.RECORD}) setting "iconName" must be a string`
+    );
+  }
+
+  if (typeof settings.iconColor !== "string") {
+    throw new Error(
+      `Component "${comp.title}" (type: ${COMPONENT_TYPE.RECORD}) setting "iconColor" must be a string`
+    );
+  }
+
+  if (typeof settings.objectType !== "number") {
+    throw new Error(
+      `Component "${comp.title}" (type: ${COMPONENT_TYPE.RECORD}) setting "objectType" must be a number`
+    );
+  }
+};
+
+const validateGlobalMenuComponentSettings = (
+  comp: UntypedManifestComponent
+): void => {
+  const settings = comp.settings as
+    | Partial<GlobalMenuComponentSettings>
+    | undefined;
+
+  if (!settings) {
+    throw new Error(
+      `Component "${comp.title}" (type: ${COMPONENT_TYPE.GLOBAL_MENU}) is missing required settings`
+    );
+  }
+
+  if (!settings.displayName) {
+    throw new Error(
+      `Component "${comp.title}" (type: ${COMPONENT_TYPE.GLOBAL_MENU}) is missing required setting: displayName`
+    );
+  }
+
+  if (typeof settings.displayName !== "string") {
+    throw new Error(
+      `Component "${comp.title}" (type: ${COMPONENT_TYPE.GLOBAL_MENU}) setting "displayName" must be a string`
+    );
+  }
+};
+
+const validateComponentSettings = (comp: UntypedManifestComponent): void => {
+  switch (comp.type) {
+    case COMPONENT_TYPE.RECORD:
+      validateRecordComponentSettings(comp);
+      break;
+    case COMPONENT_TYPE.GLOBAL_MENU:
+      validateGlobalMenuComponentSettings(comp);
+      break;
+    default:
+      throw new Error(
+        `Component "${comp.title}" has unsupported type: ${comp.type}. Supported types: ${COMPONENT_TYPE.RECORD}, ${COMPONENT_TYPE.GLOBAL_MENU}`
+      );
+  }
+};
+
 export const validateComponentBuild = async (
   componentPath: string,
-  comp: ManifestComponent
+  comp: UntypedManifestComponent
 ) => {
   if (!(await fs.pathExists(componentPath))) {
     throw new Error(
@@ -54,6 +148,8 @@ export const validateComponentBuild = async (
       throw new Error(`Component <${comp.id}> at: /${comp.path} not found`);
     }
   }
+
+  validateComponentSettings(comp);
 };
 
 export const zipComponentBuild = async (
@@ -104,7 +200,9 @@ export const zipComponentBuild = async (
 };
 
 export const validateManifestComponents = async (manifest: Manifest) => {
-  const components = manifest.components;
+  const components = manifest.components as unknown as
+    | UntypedManifestComponent[]
+    | undefined;
   if (!components || components.length === 0) {
     throw new Error("No components found in manifest");
   }
@@ -124,7 +222,8 @@ export const handleComponents = async (
   manifest: Manifest
 ): Promise<ZippedComponent[]> => {
   await validateManifestComponents(manifest);
-  const components = manifest.components!;
+  const components =
+    manifest.components as unknown as UntypedManifestComponent[];
 
   const zippedComponents: ZippedComponent[] = [];