@forgehive/forge-cli 0.3.17 → 0.5.1

package/dist/tasks/types.d.ts

@@ -19,6 +19,7 @@ export interface ForgeConf {
     project: {
         name: string;
         uuid?: string;
+        description?: string;
     };
     paths: {
         logs: string;

package/dist/test/tasks/create.test.js

@@ -19,8 +19,9 @@ const name = 'sample:newTask'
 const description = 'Add task description here'
 
 const schema = new Schema({
-  // Add your schema definitions here
-  // example: myParam: Schema.string()
+  // Add your schema definitions here.
+  // Use .describe() so the field shows up in \`forge sample:newTask --help\`.
+  // example: myParam: Schema.string().describe('What this parameter is for')
 })
 
 const boundaries = {

package/dist/utils/taskAnalysis.d.ts

@@ -1,13 +1,19 @@
 interface SchemaProperty {
     name?: string;
     type: string;
+    format?: string;
+    description?: string;
     optional?: boolean;
     default?: string;
     properties?: Record<string, SchemaProperty>;
+    additionalProperties?: SchemaProperty | {
+        anyOf: SchemaProperty[];
+    };
 }
 interface InputSchema {
     type: string;
     properties: Record<string, SchemaProperty>;
+    required?: string[];
 }
 interface OutputType {
     type: string;

package/dist/utils/taskAnalysis.js

@@ -502,64 +502,105 @@ function analyzeSchemaArg(node, sourceFile) {
         const arg = node.arguments?.[0];
         if (arg && ts.isObjectLiteralExpression(arg)) {
             const properties = {};
+            const required = [];
             arg.properties.forEach(prop => {
                 if (ts.isPropertyAssignment(prop) && ts.isIdentifier(prop.name)) {
                     const propName = prop.name.text;
                     const propValue = analyzeSchemaProp(prop.initializer, sourceFile);
+                    // Optionality is expressed by absence from `required` (JSON Schema)
+                    const isOptional = propValue.optional === true;
+                    delete propValue.optional;
                     properties[propName] = propValue;
+                    if (!isOptional) {
+                        required.push(propName);
+                    }
                 }
             });
-            return { type: 'object', properties };
+            const result = { type: 'object', properties };
+            if (required.length > 0) {
+                result.required = required;
+            }
+            return result;
         }
     }
     return { type: 'object', properties: {} };
 }
-// Enhanced schema property analysis
-function analyzeSchemaProp(node, sourceFile) {
-    // Analyze Schema.string(), Schema.number(), etc.
-    if (ts.isCallExpression(node)) {
-        if (ts.isPropertyAccessExpression(node.expression) &&
-            ts.isIdentifier(node.expression.expression) &&
-            node.expression.expression.text === 'Schema') {
-            const methodName = node.expression.name.text;
-            const baseType = { type: getSchemaTypeFromMethod(methodName) };
-            return baseType;
-        }
-    }
-    // Handle chained calls like Schema.number().optional()
-    if (ts.isCallExpression(node)) {
-        if (ts.isPropertyAccessExpression(node.expression)) {
-            const chainedMethod = node.expression.name.text;
-            if (chainedMethod === 'optional') {
-                // This is a .optional() call, get the base type
-                const baseCall = node.expression.expression;
-                if (ts.isCallExpression(baseCall)) {
-                    const baseType = analyzeSchemaProp(baseCall, sourceFile);
-                    return { ...baseType, optional: true };
-                }
+// Analyze a single schema field, unwrapping the call chain
+// (e.g. Schema.string().describe('...').optional()) into a JSON Schema property.
+function analyzeSchemaProp(node, _sourceFile) {
+    let optional = false;
+    let description;
+    let defaultValue;
+    let current = node;
+    while (ts.isCallExpression(current) && ts.isPropertyAccessExpression(current.expression)) {
+        const methodName = current.expression.name.text;
+        const inner = current.expression.expression;
+        // Base call: Schema.<type>(...)
+        if (ts.isIdentifier(inner) && inner.text === 'Schema') {
+            const prop = mapSchemaMethod(methodName);
+            if (description !== undefined) {
+                prop.description = description;
             }
-            else if (chainedMethod === 'default') {
-                // This is a .default() call, get the base type
-                const baseCall = node.expression.expression;
-                if (ts.isCallExpression(baseCall)) {
-                    const baseType = analyzeSchemaProp(baseCall, sourceFile);
-                    const defaultValue = node.arguments[0]?.getText() || 'undefined';
-                    return { ...baseType, default: defaultValue };
-                }
+            if (defaultValue !== undefined) {
+                prop.default = defaultValue;
+            }
+            if (optional) {
+                prop.optional = true;
             }
+            return prop;
         }
+        // Chained modifiers
+        if (methodName === 'optional') {
+            optional = true;
+        }
+        else if (methodName === 'describe') {
+            const arg = current.arguments[0];
+            if (arg && ts.isStringLiteral(arg)) {
+                description = arg.text;
+            }
+        }
+        else if (methodName === 'default') {
+            defaultValue = current.arguments[0]?.getText() ?? 'undefined';
+        }
+        // Other modifiers (min/max/regex/...) don't change the JSON Schema type, so
+        // we keep unwrapping until we reach the base Schema.<type>() call.
+        current = inner;
     }
     return { type: 'unknown' };
 }
-function getSchemaTypeFromMethod(methodName) {
-    const typeMap = {
-        string: 'string',
-        number: 'number',
-        boolean: 'boolean',
-        array: 'array',
-        object: 'object'
-    };
-    return typeMap[methodName] || 'unknown';
+// Map a Schema.* helper name to its JSON Schema representation, matching what
+// Schema.describe() emits at runtime.
+function mapSchemaMethod(methodName) {
+    switch (methodName) {
+        case 'string':
+            return { type: 'string' };
+        case 'number':
+            return { type: 'number' };
+        case 'boolean':
+            return { type: 'boolean' };
+        case 'date':
+            return { type: 'string', format: 'date-time' };
+        case 'email':
+            return { type: 'string', format: 'email' };
+        case 'uuid':
+            return { type: 'string', format: 'uuid' };
+        case 'url':
+            return { type: 'string', format: 'uri' };
+        case 'array':
+            return { type: 'array' };
+        case 'object':
+            return { type: 'object' };
+        case 'stringRecord':
+            return { type: 'object', additionalProperties: { type: 'string' } };
+        case 'numberRecord':
+            return { type: 'object', additionalProperties: { type: 'number' } };
+        case 'booleanRecord':
+            return { type: 'object', additionalProperties: { type: 'boolean' } };
+        case 'mixedRecord':
+            return { type: 'object', additionalProperties: { anyOf: [{ type: 'string' }, { type: 'number' }, { type: 'boolean' }] } };
+        default:
+            return { type: 'unknown' };
+    }
 }
 // Enhanced boundary analysis that extracts detailed boundary information
 function analyzeBoundariesWithTypes(node, sourceFile) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgehive/forge-cli",
-  "version": "0.3.17",
+  "version": "0.5.1",
   "description": "TypeScript CLI application",
   "license": "MIT",
   "main": "dist/index.js",
@@ -10,11 +10,11 @@
   "publishConfig": {
     "access": "public",
     "dependencies": {
-      "@forgehive/hive-sdk": "^0.1.6",
-      "@forgehive/record-tape": "^0.2.7",
-      "@forgehive/runner": "^0.2.7",
-      "@forgehive/schema": "^0.1.4",
-      "@forgehive/task": "^0.2.7",
+      "@forgehive/hive-sdk": "^0.3.0",
+      "@forgehive/record-tape": "^0.3.0",
+      "@forgehive/runner": "^0.3.0",
+      "@forgehive/schema": "^0.2.0",
+      "@forgehive/task": "^0.3.0",
       "esbuild": "^0.25.0",
       "handlebars": "^4.7.8",
       "minimist": "^1.2.8",
@@ -30,11 +30,11 @@
     "minimist": "^1.2.8",
     "typescript": "^5.3.3",
     "uuid": "^11.1.0",
-    "@forgehive/runner": "0.2.7",
-    "@forgehive/schema": "0.1.4",
-    "@forgehive/task": "0.2.7",
-    "@forgehive/record-tape": "0.2.7",
-    "@forgehive/hive-sdk": "0.1.6"
+    "@forgehive/hive-sdk": "0.3.0",
+    "@forgehive/record-tape": "0.3.0",
+    "@forgehive/task": "0.3.0",
+    "@forgehive/schema": "0.2.0",
+    "@forgehive/runner": "0.3.0"
   },
   "devDependencies": {
     "@types/archiver": "^6.0.3",

package/pnpm-workspace.yaml

@@ -0,0 +1,2 @@
+overrides:
+  '@forgehive/forge-cli': 'link:'

package/src/runner.ts

@@ -93,11 +93,88 @@ runner.load('project:link', linkProject)
 runner.load('project:unlink', unlinkProject)
 runner.load('project:sync', syncProject)
 
+function printAllHelp(): void {
+  const tasks = runner.describe()
+  console.log('Usage: forge <command> [options]')
+  console.log('')
+  console.log('Commands:')
+
+  const groups: Record<string, string[]> = {}
+  for (const name of Object.keys(tasks).sort()) {
+    const group = name.includes(':') ? name.split(':')[0] : name
+    if (!groups[group]) {
+      groups[group] = []
+    }
+    groups[group].push(name)
+  }
+
+  for (const [group, commands] of Object.entries(groups)) {
+    console.log(`\n  ${group}:`)
+    for (const cmd of commands) {
+      const desc = tasks[cmd].description || ''
+      console.log(`    ${cmd.padEnd(26)} ${desc}`)
+    }
+  }
+
+  console.log('')
+  console.log('Run "forge <command> --help" for more information on a specific command.')
+}
+
+function printTaskHelp(taskName: string): void {
+  const task = runner.getTask(taskName)
+  if (!task) {
+    return
+  }
+
+  // `describe()` returns JSON Schema: fields live under `properties`, optionality
+  // is the absence from `required`, and `description` carries the help text.
+  const schema = task.describe()
+  const properties = (schema.properties ?? {}) as Record<string, { type?: string; format?: string; description?: string }>
+  const required = new Set((schema.required ?? []) as string[])
+  const keys = Object.keys(properties)
+
+  console.log(`Usage: forge ${taskName}${keys.length > 0 ? ' [options]' : ''}`)
+  console.log('')
+
+  const desc = task.getDescription()
+  if (desc) {
+    console.log(desc)
+    console.log('')
+  }
+
+  if (keys.length > 0) {
+    console.log('Options:')
+    for (const key of keys) {
+      const field = properties[key]
+      const type = field.format ?? field.type ?? 'unknown'
+      const optional = required.has(key) ? '' : ' (optional)'
+      const description = field.description ? ` - ${field.description}` : ''
+      console.log(`  --${key.padEnd(20)} ${`${type}${optional}`.padEnd(20)}${description}`)
+    }
+    console.log('')
+  } else {
+    console.log('This command takes no options.')
+    console.log('')
+  }
+}
+
 // Set handler
 runner.setHandler(async (data: ParsedArgs): Promise<unknown> => {
   const parsedArgs = runner.parseArguments(data)
   const { taskName, action, args } = parsedArgs
 
+  const helpRequested = (args as Record<string, unknown>)?.help === true
+
+  if (helpRequested || taskName === 'undefined' || !taskName) {
+    if (helpRequested && runner.getTask(taskName)) {
+      printTaskHelp(taskName)
+    } else {
+      printAllHelp()
+    }
+    setTimeout(() => { process.exit(0) }, 100)
+    return { silent: true, outcome: 'Success', taskName, result: null }
+  }
+
   console.log('===============================================')
   console.log(`Running: ${taskName} ${action ? action : ''} ${JSON.stringify(args)}`)
   console.log('===============================================')
@@ -114,7 +191,7 @@ runner.setHandler(async (data: ParsedArgs): Promise<unknown> => {
     const commandsWithDescriptor = ['task:create', 'task:remove', 'task:publish', 'task:describe', 'task:fingerprint']
     const commandsWithRunner = ['runner:create', 'runner:remove']
     const commandsWithoutParams = ['project:unlink', 'project:sync', 'auth:clear']
-    const silentCommands = ['task:describe', 'task:list', 'auth:list', 'info']
+    const silentCommands = ['task:describe', 'task:list', 'auth:list', 'info', 'docs:download']
 
     if (commandsWithDescriptor.includes(taskName)) {
       result = await task.run({ descriptorName: action })
@@ -191,10 +268,10 @@ runner.setHandler(async (data: ParsedArgs): Promise<unknown> => {
         logs
       })
     } else if (taskName === 'project:create') {
-      const { projectName, description } = args as { projectName?: string, description?: string }
+      const { name, description } = args as { name: string, description?: string }
 
       result = await task.run({
-        projectName,
+        name,
         description
       })
     } else if (taskName === 'project:link') {

package/src/tasks/auth/add.ts

@@ -12,10 +12,10 @@ import { load as loadProfiles } from './load'
 import { type Profiles } from '../types'
 
 const schema = new Schema({
-  name: Schema.string(),
-  apiKey: Schema.string(),
-  apiSecret: Schema.string(),
-  url: Schema.string()
+  name: Schema.string().describe('The name of the profile'),
+  apiKey: Schema.string().describe('The API key for the profile'),
+  apiSecret: Schema.string().describe('The API secret for the profile'),
+  url: Schema.string().describe('The URL for the profile')
 })
 
 const boundaries = {

package/src/tasks/auth/remove.ts

@@ -12,7 +12,7 @@ import { load as loadProfiles } from './load'
 import { type Profiles } from '../types'
 
 const schema = new Schema({
-  profileName: Schema.string()
+  profileName: Schema.string().describe('The name of the auth profile to remove')
 })
 
 const boundaries = {

package/src/tasks/auth/switch.ts

@@ -12,7 +12,7 @@ import { load as loadProfiles } from './load'
 import { type Profiles } from '../types'
 
 const schema = new Schema({
-  profileName: Schema.string()
+  profileName: Schema.string().describe('The name of the auth profile to switch to')
 })
 
 const boundaries = {

package/src/tasks/bundle/create.ts

@@ -9,8 +9,8 @@ import { load as loadConf } from '../conf/load'
 import { type ForgeConf } from '../types'
 
 const schema = new Schema({
-  entryPoint: Schema.string(),
-  outputFile: Schema.string()
+  entryPoint: Schema.string().describe('Path to the task entry point file'),
+  outputFile: Schema.string().describe('Path for the bundled output file')
 })
 
 const boundaries = {

package/src/tasks/bundle/fingerprint.ts

@@ -45,8 +45,8 @@ interface FingerprintResult {
 const description = 'Generate task bundle with comprehensive fingerprinting and type extraction'
 
 const schema = new Schema({
-  descriptorName: Schema.string(),
-  filePath: Schema.string().optional()
+  descriptorName: Schema.string().describe('The task descriptor name (e.g. domain:taskName)'),
+  filePath: Schema.string().describe('Optional path to the task source file').optional()
 })
 
 const boundaries = {

package/src/tasks/bundle/load.ts

@@ -6,7 +6,7 @@ import { createTask } from '@forgehive/task'
 import { Schema } from '@forgehive/schema'
 
 const schema = new Schema({
-  bundlePath: Schema.string()
+  bundlePath: Schema.string().describe('Path to the bundle file to load')
 })
 
 const boundaries = {}

package/src/tasks/bundle/zip.ts

@@ -11,10 +11,10 @@ import path from 'path'
 const description = 'Zip a bundle file for distribution'
 
 const schema = new Schema({
-  dir: Schema.string(),
-  input: Schema.string(),
-  output: Schema.string(),
-  forgeJsonPath: Schema.string().optional() // Optional path to forge.json - if provided, it will be included
+  dir: Schema.string().describe('Directory that will contain the generated zip'),
+  input: Schema.string().describe('Path to the file or folder to add to the zip'),
+  output: Schema.string().describe('Output path for the generated zip file'),
+  forgeJsonPath: Schema.string().describe('Optional path to forge.json to include in the bundle').optional() // Optional path to forge.json - if provided, it will be included
 })
 
 const boundaries = {

package/src/tasks/docs/download.ts

@@ -16,8 +16,8 @@ const LLM_GUIDE_URL = 'https://raw.githubusercontent.com/forge-and-hive/forge-mo
 const LLM_HIVE_LOGGING_URL = 'https://raw.githubusercontent.com/forge-and-hive/forge-mono-repo/refs/heads/main/docs/llm-hive-logging.md'
 
 const schema = new Schema({
-  path: Schema.string().optional(),
-  logs: Schema.boolean().optional()
+  path: Schema.string().describe('Optional output path for the downloaded docs').optional(),
+  logs: Schema.boolean().describe('Include execution logs in the downloaded docs').optional()
 })
 
 const boundaries = {
@@ -92,6 +92,7 @@ export const download = createTask({
 
     // Download Hive logging guide if --logs flag is provided
     if (logs) {
+      console.log('===============================================')
       const logsTargetPath = customPath
         ? path.join(path.dirname(customPath), 'hive-logging.md')
         : 'docs/hive-logging.md'
@@ -125,6 +126,8 @@ export const download = createTask({
       })
     }
 
+    console.log('===============================================')
+
     return {
       success: true,
       downloads: results,

package/src/tasks/fixture/download.ts

@@ -26,7 +26,7 @@ interface FixtureResponse {
 const description = 'Download a fixture by UUID to a path based on task descriptor returned from API'
 
 const schema = new Schema({
-  uuid: Schema.string()
+  uuid: Schema.string().describe('The UUID of the fixture to download')
 })
 
 const boundaries = {

package/src/tasks/init.ts

@@ -7,7 +7,7 @@ import { Schema } from '@forgehive/schema'
 import { type ForgeConf } from './types'
 
 const schema = new Schema({
-  dryRun: Schema.boolean().optional()
+  dryRun: Schema.boolean().describe('Preview the changes without writing any files').optional()
 })
 
 const boundaries = {

package/src/tasks/project/create.ts

@@ -12,12 +12,12 @@ import { load as loadConf } from '../conf/load'
 import { loadCurrent as loadCurrentProfile } from '../auth/loadCurrent'
 import { type ForgeConf, type Profile } from '../types'
 
-const name = 'project:create'
-const description = 'Create a new project in ForgeHive'
+const taskName = 'project:create'
+const taskDescription = 'Create a new project in ForgeHive'
 
 const schema = new Schema({
-  projectName: Schema.string().optional(),
-  description: Schema.string().optional()
+  name: Schema.string().describe('The name of the project'),
+  description: Schema.string().describe('Optional description of the project').optional()
 })
 
 const boundaries = {
@@ -40,39 +40,33 @@ const boundaries = {
 }
 
 export const create = createTask({
-  name,
-  description,
+  name: taskName,
+  description: taskDescription,
   schema,
   boundaries,
   fn: async function (argv, { loadConf, loadCurrentProfile, writeFile, createProject }) {
-    const { projectName: inputProjectName, description } = argv
+    const { name: projectName, description } = argv
 
     // Load current configuration
     const conf = await loadConf({})
 
-    // Use provided projectName or fall back to forge.json project name
-    const projectName = inputProjectName || conf.project.name
-
-    if (!projectName) {
-      throw new Error('Project name is required. Provide --projectName or ensure forge.json has a project name.')
-    }
-
     // Check if project already has a UUID, generate one if not
-    let projectUuid = conf.project.uuid
-    if (!projectUuid) {
-      projectUuid = uuidv4()
-
-      // Update forge.json with the new UUID
-      const forgePath = path.join(process.cwd(), 'forge.json')
-      const updatedConf: ForgeConf = {
-        ...conf,
-        project: {
-          ...conf.project,
-          uuid: projectUuid
-        }
+    const projectUuid = conf.project.uuid || uuidv4()
+
+    // Update forge.json with the project name and UUID
+    const forgePath = path.join(process.cwd(), 'forge.json')
+    const updatedConf: ForgeConf = {
+      ...conf,
+      project: {
+        ...conf.project,
+        name: projectName,
+        uuid: projectUuid
       }
+    }
 
-      await writeFile(forgePath, JSON.stringify(updatedConf, null, 2))
+    await writeFile(forgePath, JSON.stringify(updatedConf, null, 2))
+    console.log(`Updated forge.json with project name: ${projectName}`)
+    if (!conf.project.uuid) {
       console.log(`Generated and saved project UUID: ${projectUuid}`)
     }
 

package/src/tasks/project/link.ts

@@ -15,7 +15,7 @@ const name = 'project:link'
 const description = 'Link an existing remote project to the local project by UUID'
 
 const schema = new Schema({
-  uuid: Schema.string()
+  uuid: Schema.string().describe('The UUID of the project to link')
 })
 
 const boundaries = {

package/src/tasks/project/sync.ts

@@ -26,6 +26,8 @@ const boundaries = {
   },
   syncTasksToHive: async (
     projectUuid: string,
+    projectName: string,
+    projectDescription: string | undefined,
     tasks: Array<{ uuid: string; name: string }>,
     apiKey: string,
     apiSecret: string,
@@ -57,7 +59,7 @@ const boundaries = {
           'Content-Type': 'application/json',
           'Authorization': `Bearer ${apiKey}:${apiSecret}`
         },
-        body: JSON.stringify({ tasks })
+        body: JSON.stringify({ projectName, description: projectDescription, tasks })
       })
 
       if (response.ok) {
@@ -134,11 +136,17 @@ export const sync = createTask({
     }
 
     console.log(`  📊 Found ${tasksToSync.length} tasks to sync`)
+    console.log(`  📝 Project name: ${forge.project.name}`)
+    if (forge.project.description) {
+      console.log(`  📝 Project description: ${forge.project.description}`)
+    }
 
     try {
       const profile = await loadCurrentProfile({})
       const result = await syncTasksToHive(
         forge.project.uuid,
+        forge.project.name,
+        forge.project.description,
         tasksToSync,
         profile.apiKey,
         profile.apiSecret,

package/src/tasks/runner/bundle.ts

@@ -11,8 +11,8 @@ import { load as loadConf } from '../conf/load'
 import { type ForgeConf } from '../types'
 
 const schema = new Schema({
-  runnerName: Schema.string(),
-  targetPath: Schema.string()
+  runnerName: Schema.string().describe('The name of the runner to bundle'),
+  targetPath: Schema.string().describe('Target path for the bundled runner')
 })
 
 const boundaries = {

package/src/tasks/runner/create.ts

@@ -30,7 +30,7 @@ export { {{ runnerName }}Runner }
 `
 
 const schema = new Schema({
-  runnerName: Schema.string()
+  runnerName: Schema.string().describe('The name of the runner to create')
 })
 
 const boundaries = {

package/src/tasks/runner/remove.ts

@@ -11,7 +11,7 @@ import { load } from '../conf/load'
 import { type ForgeConf } from '../types'
 
 const schema = new Schema({
-  runnerName: Schema.string()
+  runnerName: Schema.string().describe('The name of the runner to remove')
 })
 
 const boundaries = {

package/src/tasks/task/createTask.ts

@@ -24,8 +24,9 @@ const name = '{{ taskDescriptor }}'
 const description = 'Add task description here'
 
 const schema = new Schema({
-  // Add your schema definitions here
-  // example: myParam: Schema.string()
+  // Add your schema definitions here.
+  // Use .describe() so the field shows up in \`forge {{ taskDescriptor }} --help\`.
+  // example: myParam: Schema.string().describe('What this parameter is for')
 })
 
 const boundaries = {