aios-core 3.5.0 → 3.7.0

package/.aios-core/development/tasks/create-service.md

@@ -0,0 +1,391 @@
+# Create Service
+
+## Purpose
+
+Create a new service using standardized Handlebars templates from WIS-10. Generates consistent TypeScript service structures with proper configuration, testing, and documentation.
+
+## Task Definition (AIOS Task Format V1.0)
+
+```yaml
+task: createService()
+agent: "@dev"
+responsável: Dex (Developer)
+responsavel_type: Agente
+atomic_layer: Config
+
+elicit: true
+
+inputs:
+  - name: service_name
+    type: string
+    required: true
+    pattern: "^[a-z][a-z0-9-]*$"
+    validation: Must be kebab-case, start with letter
+
+  - name: service_type
+    type: enum
+    options: ["api-integration", "utility", "agent-tool"]
+    required: true
+    default: "utility"
+
+  - name: has_auth
+    type: boolean
+    required: false
+    default: false
+
+  - name: description
+    type: string
+    required: true
+    validation: Non-empty, max 200 characters
+
+  - name: env_vars
+    type: array
+    required: false
+    default: []
+
+outputs:
+  - name: service_directory
+    type: directory
+    location: ".aios-core/infrastructure/services/{service_name}/"
+    persistido: true
+
+  - name: files_created
+    type: array
+    destino: Memory
+    persistido: false
+```
+
+---
+
+## Pre-Conditions
+
+```yaml
+pre-conditions:
+  - [ ] WIS-10 templates exist at .aios-core/development/templates/service-template/
+    tipo: pre-condition
+    blocker: true
+    validação: Check template directory exists with required .hbs files
+    error_message: "Templates not found. Run WIS-10 first."
+
+  - [ ] Service name is unique (no existing service with same name)
+    tipo: pre-condition
+    blocker: true
+    validação: Check .aios-core/infrastructure/services/{name}/ does not exist
+    error_message: "Service '{name}' already exists. Choose a different name."
+
+  - [ ] Service name follows kebab-case pattern
+    tipo: pre-condition
+    blocker: true
+    validação: Regex match ^[a-z][a-z0-9-]*$
+    error_message: "Invalid name. Use kebab-case (e.g., my-api-service)"
+```
+
+---
+
+## Interactive Elicitation Process
+
+### Step 1: Service Name
+```
+ELICIT: Service Name
+
+What is the service name?
+(Use kebab-case, e.g., "github-api", "file-processor", "auth-helper")
+
+→ Validation: ^[a-z][a-z0-9-]*$
+→ Check: Unique (not existing)
+→ On invalid: Re-prompt with error message
+```
+
+### Step 2: Service Type
+```
+ELICIT: Service Type
+
+What type of service is this?
+
+1. api-integration - External API client with rate limiting and auth
+2. utility - Internal helper/utility service
+3. agent-tool - Tool for AIOS agents
+
+→ Default: utility
+→ If api-integration: Enable client.ts generation
+```
+
+### Step 3: Authentication
+```
+ELICIT: Authentication Required
+
+Does this service require authentication?
+
+1. Yes - Include auth configuration and secure headers
+2. No - No authentication needed
+
+→ Default: No
+→ If Yes: Add auth placeholders to config
+```
+
+### Step 4: Description
+```
+ELICIT: Service Description
+
+Brief description of the service:
+(Max 200 characters, will appear in README and JSDoc)
+
+→ Validation: Non-empty, <= 200 chars
+```
+
+### Step 5: Environment Variables
+```
+ELICIT: Environment Variables
+
+What environment variables does this service need?
+(Enter comma-separated list, or 'none')
+
+Examples: API_KEY, BASE_URL, TIMEOUT_MS
+
+→ Default: none
+→ Parse: Split by comma, trim whitespace
+→ Generate: .env.example entries
+```
+
+---
+
+## Implementation Steps
+
+### Step 1: Validate Inputs
+```javascript
+// Validate service_name
+const namePattern = /^[a-z][a-z0-9-]*$/;
+if (!namePattern.test(serviceName)) {
+  throw new Error(`Invalid service name: ${serviceName}. Use kebab-case.`);
+}
+
+// Check uniqueness
+const targetDir = `.aios-core/infrastructure/services/${serviceName}/`;
+if (fs.existsSync(targetDir)) {
+  throw new Error(`Service '${serviceName}' already exists.`);
+}
+```
+
+### Step 2: Load Templates
+```javascript
+const templateDir = '.aios-core/development/templates/service-template/';
+const templates = [
+  'README.md.hbs',
+  'index.ts.hbs',
+  'types.ts.hbs',
+  'errors.ts.hbs',
+  'package.json.hbs',
+  'tsconfig.json',      // Static (no .hbs)
+  'jest.config.js',     // Static (no .hbs)
+  '__tests__/index.test.ts.hbs'
+];
+
+// Conditional: client.ts.hbs only for api-integration
+if (serviceType === 'api-integration') {
+  templates.push('client.ts.hbs');
+}
+```
+
+### Step 3: Prepare Template Context
+```javascript
+const context = {
+  serviceName: serviceName,                    // kebab-case
+  pascalCase: toPascalCase(serviceName),       // PascalCase
+  camelCase: toCamelCase(serviceName),         // camelCase
+  description: description,
+  isApiIntegration: serviceType === 'api-integration',
+  hasAuth: hasAuth,
+  envVars: envVars.map(v => ({
+    name: v,
+    description: `${v} environment variable`
+  })),
+  storyId: 'WIS-11',
+  createdAt: new Date().toISOString().split('T')[0]
+};
+```
+
+### Step 4: Generate Files
+```javascript
+// Create target directory
+fs.mkdirSync(targetDir, { recursive: true });
+fs.mkdirSync(`${targetDir}__tests__/`, { recursive: true });
+
+// Process each template
+for (const templateFile of templates) {
+  const templatePath = `${templateDir}${templateFile}`;
+  const isHandlebars = templateFile.endsWith('.hbs');
+
+  // Determine output filename
+  const outputFile = isHandlebars
+    ? templateFile.replace('.hbs', '')
+    : templateFile;
+  const outputPath = `${targetDir}${outputFile}`;
+
+  if (isHandlebars) {
+    // Render Handlebars template
+    const template = fs.readFileSync(templatePath, 'utf8');
+    const compiled = Handlebars.compile(template);
+    const content = compiled(context);
+    fs.writeFileSync(outputPath, content);
+  } else {
+    // Copy static file
+    fs.copyFileSync(templatePath, outputPath);
+  }
+}
+```
+
+### Step 5: Post-Generation
+```bash
+# Navigate to service directory
+cd .aios-core/infrastructure/services/{service_name}/
+
+# Install dependencies
+npm install
+
+# Build TypeScript
+npm run build
+
+# Run tests
+npm test
+```
+
+---
+
+## Handlebars Helpers Required
+
+The following helpers must be available:
+
+```javascript
+Handlebars.registerHelper('pascalCase', (str) => {
+  return str.split('-').map(word =>
+    word.charAt(0).toUpperCase() + word.slice(1)
+  ).join('');
+});
+
+Handlebars.registerHelper('camelCase', (str) => {
+  const pascal = str.split('-').map(word =>
+    word.charAt(0).toUpperCase() + word.slice(1)
+  ).join('');
+  return pascal.charAt(0).toLowerCase() + pascal.slice(1);
+});
+
+Handlebars.registerHelper('kebabCase', (str) => {
+  return str.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
+});
+
+Handlebars.registerHelper('upperCase', (str) => {
+  return str.toUpperCase().replace(/-/g, '_');
+});
+```
+
+---
+
+## Post-Conditions
+
+```yaml
+post-conditions:
+  - [ ] All template files generated successfully
+    tipo: post-condition
+    blocker: true
+    validação: Verify all expected files exist in target directory
+
+  - [ ] TypeScript compiles without errors
+    tipo: post-condition
+    blocker: false
+    validação: Run npm run build, check exit code
+
+  - [ ] Tests pass
+    tipo: post-condition
+    blocker: false
+    validação: Run npm test, check exit code
+```
+
+---
+
+## Error Handling
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| Service name exists | Directory already present | Prompt for different name |
+| Template not found | WIS-10 not installed | Error: "Run WIS-10 first" |
+| npm install fails | Network/package issues | Warning, continue without deps |
+| Build fails | TypeScript errors | Warning, show errors, continue |
+| Invalid name format | Name not kebab-case | Re-prompt with validation error |
+
+**Error Recovery Strategy:**
+```javascript
+// Atomic generation - rollback on failure
+try {
+  generateAllFiles(targetDir, templates, context);
+} catch (error) {
+  // Clean up partial files
+  if (fs.existsSync(targetDir)) {
+    fs.rmSync(targetDir, { recursive: true, force: true });
+  }
+  throw error;
+}
+```
+
+---
+
+## Performance
+
+```yaml
+duration_expected: 5-30s (excluding npm install)
+cost_estimated: $0.002-0.005
+token_usage: ~1,000-2,000 tokens
+```
+
+---
+
+## Success Output
+
+```
+============================================
+ SERVICE CREATED SUCCESSFULLY
+============================================
+
+ Service: {service_name}
+ Type: {service_type}
+ Location: .aios-core/infrastructure/services/{service_name}/
+
+ Files Created:
+   README.md
+   index.ts
+   types.ts
+   errors.ts
+   client.ts (if api-integration)
+   package.json
+   tsconfig.json
+   jest.config.js
+   __tests__/index.test.ts
+
+ Next Steps:
+   1. cd .aios-core/infrastructure/services/{service_name}
+   2. Review generated code
+   3. Implement service methods in index.ts
+   4. Add tests in __tests__/
+   5. Update environment variables as needed
+
+============================================
+```
+
+---
+
+## Metadata
+
+```yaml
+story: WIS-11
+version: 1.0.0
+created: 2025-12-24
+author: "@dev (Dex)"
+dependencies:
+  templates:
+    - service-template/ (from WIS-10)
+  tasks: []
+tags:
+  - service-generation
+  - scaffolding
+  - handlebars
+  - typescript
+```

package/.aios-core/development/templates/service-template/README.md.hbs

@@ -0,0 +1,158 @@
+# {{pascalCase serviceName}} Service
+
+> {{description}}
+
+## Installation
+
+```bash
+npm install @aios/{{kebabCase serviceName}}
+```
+
+## Quick Start
+
+```typescript
+import { create{{pascalCase serviceName}}Service } from '@aios/{{kebabCase serviceName}}';
+
+const service = create{{pascalCase serviceName}}Service({
+{{#each envVars}}
+  {{camelCase this.name}}: process.env.{{this.name}},
+{{/each}}
+});
+
+// Use the service
+const result = await service.execute();
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+{{#each envVars}}
+| `{{this.name}}` | {{#if this.required}}Yes{{else}}No{{/if}} | {{this.description}} |
+{{/each}}
+
+### Programmatic Configuration
+
+```typescript
+import { create{{pascalCase serviceName}}Service, {{pascalCase serviceName}}Config } from '@aios/{{kebabCase serviceName}}';
+
+const config: {{pascalCase serviceName}}Config = {
+{{#each envVars}}
+  {{camelCase this.name}}: '{{this.example}}',
+{{/each}}
+};
+
+const service = create{{pascalCase serviceName}}Service(config);
+```
+
+{{#if isApiIntegration}}
+## API Integration
+
+This service integrates with an external API. Features include:
+
+- **Rate Limiting**: Automatic request throttling
+- **Retry Logic**: Exponential backoff on failures
+- **Error Handling**: Typed errors with actionable messages
+
+### Rate Limits
+
+> **Note:** The values below are placeholders. Update them according to your API's actual rate limits.
+
+| Tier | Requests/min | Burst |
+|------|--------------|-------|
+| Free | 60 | 10 |
+| Pro | 600 | 100 |
+
+{{/if}}
+## Usage Examples
+
+### Basic Usage
+
+```typescript
+const service = create{{pascalCase serviceName}}Service(config);
+
+try {
+  const result = await service.execute();
+  console.log('Success:', result);
+} catch (error) {
+  if (error instanceof {{pascalCase serviceName}}Error) {
+    console.error('Service error:', error.code, error.message);
+  }
+  throw error;
+}
+```
+
+{{#if hasAuth}}
+### Authentication
+
+This service requires authentication. Set your credentials via environment variables or config:
+
+```typescript
+const service = create{{pascalCase serviceName}}Service({
+  apiKey: process.env.{{upperCase serviceName}}_API_KEY,
+  // or
+  accessToken: process.env.{{upperCase serviceName}}_ACCESS_TOKEN,
+});
+```
+
+{{/if}}
+## Error Handling
+
+The service provides typed errors for common failure scenarios:
+
+```typescript
+import { {{pascalCase serviceName}}Error, {{pascalCase serviceName}}ErrorCode } from '@aios/{{kebabCase serviceName}}';
+
+try {
+  await service.execute();
+} catch (error) {
+  if (error instanceof {{pascalCase serviceName}}Error) {
+    switch (error.code) {
+      case {{pascalCase serviceName}}ErrorCode.CONFIGURATION_ERROR:
+        // Handle configuration issues
+        break;
+      case {{pascalCase serviceName}}ErrorCode.NETWORK_ERROR:
+        // Handle network issues
+        break;
+{{#if isApiIntegration}}
+      case {{pascalCase serviceName}}ErrorCode.RATE_LIMIT_EXCEEDED:
+        // Handle rate limiting
+        break;
+{{/if}}
+      default:
+        // Handle other errors
+    }
+  }
+}
+```
+
+## API Reference
+
+See the [TypeScript definitions](./dist/types.d.ts) for complete API documentation.
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Build
+npm run build
+
+# Type check
+npm run typecheck
+```
+
+## License
+
+MIT
+
+---
+
+*Generated by AIOS-FullStack Service Template*
+*Story: {{storyId}}*