@forgehive/forge-cli 0.3.18 → 0.5.1

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 = {

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

@@ -16,8 +16,8 @@ const taskName = 'project:create'
 const taskDescription = 'Create a new project in ForgeHive'
 
 const schema = new Schema({
-  name: Schema.string(),
-  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 = {

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/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 = {

package/src/tasks/task/describe.ts

@@ -17,7 +17,7 @@ import { type ForgeConf } from '../types'
 const description = 'Describe a task with detailed information about its schema, boundaries and configuration'
 
 const schema = new Schema({
-  descriptorName: Schema.string()
+  descriptorName: Schema.string().describe('The task descriptor name to describe (e.g. domain:taskName)')
 })
 
 const boundaries = {

package/src/tasks/task/download.ts

@@ -13,8 +13,8 @@ import { loadCurrent as loadCurrentProfile } from '../auth/loadCurrent'
 import { Profile, type ForgeConf } from '../types'
 
 const schema = new Schema({
-  descriptorName: Schema.string(),
-  uuid: Schema.string()
+  descriptorName: Schema.string().describe('The task descriptor name (e.g. domain:taskName)'),
+  uuid: Schema.string().describe('The UUID of the task version to download')
 })
 
 const boundaries = {

package/src/tasks/task/fingerprint.ts

@@ -12,7 +12,7 @@ import { fingerprint as bundleFingerprint } from '../bundle/fingerprint'
 const description = 'Analyze a specific task and generate detailed fingerprint without bundling'
 
 const schema = new Schema({
-  descriptorName: Schema.string()
+  descriptorName: Schema.string().describe('The task descriptor name to fingerprint (e.g. domain:taskName)')
 })
 
 const boundaries = {

package/src/tasks/task/invoke.ts

@@ -14,8 +14,8 @@ const name = 'task:invoke'
 const description = 'Invoke a deployed task remotely using the Hive API'
 
 const schema = new Schema({
-  descriptorName: Schema.string(),
-  json: Schema.string()
+  descriptorName: Schema.string().describe('The task descriptor name (e.g. domain:taskName)'),
+  json: Schema.string().describe('JSON string of arguments to pass to the task')
 })
 
 const boundaries = {

package/src/tasks/task/publish.ts

@@ -20,7 +20,7 @@ import { Profile } from '../types'
 import { TaskFingerprintOutput } from '../../utils/taskAnalysis'
 
 const schema = new Schema({
-  descriptorName: Schema.string()
+  descriptorName: Schema.string().describe('The task descriptor name to publish (e.g. domain:taskName)')
 })
 
 const boundaries = {

package/src/tasks/task/remove.ts

@@ -11,7 +11,7 @@ import { load } from '../conf/load'
 import { type ForgeConf } from '../types'
 
 const schema = new Schema({
-  descriptorName: Schema.string()
+  descriptorName: Schema.string().describe('The task descriptor name to remove (e.g. domain:taskName)')
 })
 
 const boundaries = {

package/src/tasks/task/replay.ts

@@ -30,9 +30,9 @@ interface Fixture {
 const description = 'Replay a task execution from a specified path'
 
 const schema = new Schema({
-  descriptorName: Schema.string(),
-  path: Schema.string(),
-  cache: Schema.string().optional()
+  descriptorName: Schema.string().describe('The task descriptor name to replay (e.g. domain:taskName)'),
+  path: Schema.string().describe('Path to the execution log fixture to replay'),
+  cache: Schema.string().describe('Cache mode for boundaries during replay').optional()
 })
 
 const boundaries = {

package/src/tasks/task/run.ts

@@ -21,8 +21,8 @@ import { type ForgeConf, type Profile } from '../types'
 // For now, we'll use a simple schema without the record type
 // TODO: Use Schema.record once it's properly built and available
 const schema = new Schema({
-  descriptorName: Schema.string(),
-  args: Schema.mixedRecord()
+  descriptorName: Schema.string().describe('The task descriptor name to run (e.g. domain:taskName)'),
+  args: Schema.mixedRecord().describe('Arguments to pass to the task')
   // args will be passed directly without schema validation for now
 })
 

package/src/test/tasks/create.test.ts

@@ -16,8 +16,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/src/utils/taskAnalysis.ts

@@ -9,14 +9,22 @@ interface TaskLocation {
 interface SchemaProperty {
   name?: string
   type: string
+  format?: string
+  description?: string
+  // Internal marker used while building the schema; stripped in favour of the
+  // object-level `required` array (JSON Schema semantics) before output.
   optional?: boolean
   default?: string
   properties?: Record<string, SchemaProperty>
+  additionalProperties?: SchemaProperty | { anyOf: SchemaProperty[] }
 }
 
+// JSON Schema (draft 2020-12) representation of the task input, matching what
+// `Schema.describe()` produces at runtime.
 interface InputSchema {
   type: string
   properties: Record<string, SchemaProperty>
+  required?: string[]
 }
 
 interface OutputType {
@@ -558,69 +566,110 @@ function analyzeSchemaArg(node: ts.Expression, sourceFile: ts.SourceFile): Input
     const arg = node.arguments?.[0]
     if (arg && ts.isObjectLiteralExpression(arg)) {
       const properties: Record<string, SchemaProperty> = {}
+      const required: string[] = []
       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: InputSchema = { type: 'object', properties }
+      if (required.length > 0) {
+        result.required = required
+      }
+      return result
     }
   }
   return { type: 'object', properties: {} }
 }
 
-// Enhanced schema property analysis
-function analyzeSchemaProp(node: ts.Expression, sourceFile: ts.SourceFile): SchemaProperty {
-  // 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: SchemaProperty = { type: getSchemaTypeFromMethod(methodName) }
-
-      return baseType
+// Analyze a single schema field, unwrapping the call chain
+// (e.g. Schema.string().describe('...').optional()) into a JSON Schema property.
+function analyzeSchemaProp(node: ts.Expression, _sourceFile: ts.SourceFile): SchemaProperty {
+  let optional = false
+  let description: string | undefined
+  let defaultValue: string | undefined
+
+  let current: ts.Expression = 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
+      }
+      if (defaultValue !== undefined) {
+        prop.default = defaultValue
+      }
+      if (optional) {
+        prop.optional = true
+      }
+      return prop
     }
-  }
 
-  // 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 }
-        }
-      } 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 }
-        }
+    // 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: string): string {
-  const typeMap: Record<string, string> = {
-    string: 'string',
-    number: 'number',
-    boolean: 'boolean',
-    array: 'array',
-    object: 'object'
+// Map a Schema.* helper name to its JSON Schema representation, matching what
+// Schema.describe() emits at runtime.
+function mapSchemaMethod(methodName: string): SchemaProperty {
+  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' }
   }
-  return typeMap[methodName] || 'unknown'
 }
 
 

package/logs/bundle:fingerprint.log

@@ -1 +0,0 @@
-{"input":{"filePath":"/Users/danielzavaladlvega/forgehive/forge-mono-repo/apps/sample-project/src/tasks/test/errors.ts"},"boundaries":{"getCwd":[],"loadConf":[],"readFile":[],"writeFile":[],"ensureFingerprintsFolder":[]},"metadata":{"environment":"cli"},"metrics":[],"type":"error","error":"Invalid input on: descriptorName: Required"}