@majkapp/plugin-kit 3.7.3 → 3.7.4

package/docs/REPORTS.md

@@ -0,0 +1,271 @@
+# Reports API
+
+Knowledge management with witness-based validation, hierarchical organization, and views.
+
+## Quick Start
+
+```typescript
+handler: async (input, ctx) => {
+  // Write a report
+  const result = await ctx.majk.reports.write_report({
+    path: '/research/api-analysis.md',
+    content: '# API Analysis\n\nFindings from the API review...',
+    title: 'API Analysis Report',
+    tags: ['research', 'api'],
+    witness: { file: { path: 'src/api.ts', exists: true } }
+  });
+
+  // Read it back
+  const report = await ctx.majk.reports.read_report({ report: result.id });
+  return { reportId: result.id };
+}
+```
+
+## API Reference
+
+### write_report(input)
+
+Write a report to the knowledge base.
+
+```typescript
+const result = await ctx.majk.reports.write_report({
+  content: string,              // Markdown content
+  path: string,                 // Path like '/research/topic.md'
+  title?: string,
+  partOf?: { parent: string, placeholder?: string },  // Hierarchical relationship
+  refs?: string[],              // Related report IDs
+  tags?: string[],
+  status?: string,              // 'draft', 'review', 'final'
+  witness?: Witness             // Validation criteria
+});
+// Returns: { id, path, uri, title?, hasWitness, created }
+```
+
+### read_report(input)
+
+Read a report with optional content expansion.
+
+```typescript
+const report = await ctx.majk.reports.read_report({
+  report: string,               // ID or path
+  view?: string,                // View name
+  expand?: 'link' | 'inline' | 'inline-linked',
+  expandDepth?: number,
+  offset?: number,              // Line offset
+  limit?: number,               // Line limit
+  validate?: boolean,           // Run witness validation
+  workingDirectory?: string
+});
+// Returns: { id, path, content, validation, ... }
+```
+
+### list_reports(input?)
+
+List and search reports.
+
+```typescript
+const { reports, total, hasMore } = await ctx.majk.reports.list_reports({
+  view?: string,
+  pathPrefix?: string,          // Filter by path prefix
+  tags?: string[],
+  status?: string,
+  hasWitness?: boolean,
+  search?: string,              // Text search
+  limit?: number,
+  offset?: number
+});
+```
+
+### delete_report(input)
+
+Delete a report.
+
+```typescript
+const { deleted } = await ctx.majk.reports.delete_report({ report: string });
+```
+
+### update_report(input)
+
+Update with line-based edits.
+
+```typescript
+const result = await ctx.majk.reports.update_report({
+  report: string,
+  edits: [
+    { line: 5, content: 'Updated line 5' },
+    { lines: [10, 15], content: 'Replace lines 10-15' },
+    { after: 20, content: 'Insert after line 20' },
+    { line: 25, delete: true }
+  ],
+  validate?: boolean
+});
+```
+
+### reorganize_reports(input)
+
+Batch move reports.
+
+```typescript
+const result = await ctx.majk.reports.reorganize_reports({
+  moves: [
+    { from: '/old/path.md', to: '/new/path.md' }
+  ]
+});
+```
+
+## Template Workflow
+
+### start_report(input)
+
+Start a report from a template.
+
+```typescript
+const draft = await ctx.majk.reports.start_report({
+  template: 'research-report',
+  topic: 'API Security',
+  sections: { summary: 'Initial findings...' },
+  refs: { codebase: ['src/api.ts', 'src/auth.ts'] }
+});
+// Returns: { handle, preview, missing: { sections, refs } }
+```
+
+### update_draft(input)
+
+Update a draft report.
+
+```typescript
+const updated = await ctx.majk.reports.update_draft({
+  handle: string,
+  sections: { analysis: 'Detailed analysis...' },
+  refs: { tests: 'tests/api.test.ts' }
+});
+```
+
+### preview_draft(input)
+
+Preview before finalizing.
+
+```typescript
+const preview = await ctx.majk.reports.preview_draft({
+  handle: string,
+  validate: true
+});
+// Returns: { rendered, missing, validation?, ready }
+```
+
+### finalize_report(input)
+
+Finalize and save the report.
+
+```typescript
+const result = await ctx.majk.reports.finalize_report({
+  handle: string,
+  force?: boolean  // Finalize even with validation warnings
+});
+```
+
+## Views
+
+### create_view(input)
+
+Create an LLM-powered view.
+
+```typescript
+const view = await ctx.majk.reports.create_view({
+  name: 'Security Review',
+  philosophy: 'Organize reports by security domain and risk level',
+  categorizeExisting: true
+});
+```
+
+### list_views()
+
+```typescript
+const { views } = await ctx.majk.reports.list_views();
+// views: Array<{ id, name, isDefault, reportCount }>
+```
+
+### get_view_structure(input)
+
+Get view tree structure.
+
+```typescript
+const structure = await ctx.majk.reports.get_view_structure({ view: 'Security Review' });
+// Returns: { viewId, viewName, tree, reportCount }
+```
+
+### delete_view(input)
+
+```typescript
+const { deleted } = await ctx.majk.reports.delete_view({ view: string });
+```
+
+## Import/Export
+
+### import_document(input)
+
+Import a file into the knowledge base.
+
+```typescript
+const result = await ctx.majk.reports.import_document({
+  file: '/path/to/document.md',
+  topic: 'research',
+  title: 'Imported Doc',
+  tags: ['imported'],
+  cleanup: true  // Delete source after import
+});
+```
+
+### export_report(input)
+
+Export a report to file.
+
+```typescript
+const result = await ctx.majk.reports.export_report({
+  report: string,
+  outputPath: '/output/report.pdf',
+  format: 'markdown' | 'html' | 'pdf' | 'docx',
+  mode: 'single' | 'hierarchy' | 'inlined'
+});
+```
+
+### export_all_reports(input)
+
+Export all reports.
+
+```typescript
+const result = await ctx.majk.reports.export_all_reports({
+  outputDir: '/output/',
+  format: 'markdown'
+});
+```
+
+## Hierarchical Reports
+
+```typescript
+// Create master report
+const master = await ctx.majk.reports.write_report({
+  path: '/research/security/security.md',
+  content: '# Security Analysis\n\n{{@section:auth}}\n{{@section:api}}'
+});
+
+// Create child sections
+await ctx.majk.reports.write_report({
+  path: '/research/security/sections/01-auth.md',
+  content: '## Authentication\n...',
+  partOf: { parent: master.id, placeholder: 'auth' }
+});
+```
+
+## Best Practices
+
+1. **Use meaningful paths** - Organize reports hierarchically
+2. **Add witnesses** - Validate reports stay accurate
+3. **Use views** - Organize reports by perspective
+4. **Tag consistently** - Enable filtering and discovery
+5. **Use templates** - Ensure consistent report structure
+
+## Next Steps
+
+Run `npx @majkapp/plugin-kit --knowledge` - Knowledge tree API
+Run `npx @majkapp/plugin-kit --delegation` - Task delegation

package/docs/SCRIPTING.md

@@ -0,0 +1,231 @@
+# Scripting API
+
+Execute JavaScript scripts that orchestrate tool calls with tracing and dry-run support.
+
+## Quick Start
+
+```typescript
+handler: async (input, ctx) => {
+  const result = await ctx.majk.scripting.execute_script({
+    code: `
+      const reports = await tools.ReportsService.list_reports({ limit: 10 });
+      console.log('Found', reports.total, 'reports');
+      return { count: reports.total };
+    `,
+    dryRun: false
+  });
+
+  return result.result;
+}
+```
+
+## API Reference
+
+### execute_script(input)
+
+Execute a JavaScript script.
+
+```typescript
+const result = await ctx.majk.scripting.execute_script({
+  code?: string,                    // JavaScript code to execute
+  rerun?: string,                   // Trace ID to re-run
+  params?: Record<string, unknown>, // Parameters available as `params`
+  dryRun?: boolean,                 // Mock write operations
+  dryRunOptions?: {
+    maxAIMocks?: number             // Limit AI mock responses
+  },
+  timeoutMs?: number                // Execution timeout
+});
+
+// Returns:
+{
+  success: boolean,
+  result?: any,                     // Script return value
+  error?: ScriptError,
+  traceId: string,                  // For debugging/re-running
+  traceFormatted: string,           // Human-readable trace
+  trace: {
+    summary: ScriptTraceSummary,
+    events: ScriptTraceEvent[],
+    toolCalls?: ScriptToolCallRecord[]
+  }
+}
+```
+
+### Tool Access in Scripts
+
+Scripts access tools via the `tools` object:
+
+```javascript
+// Pattern: tools.ServiceName.function_name(params)
+
+// Reports
+const reports = await tools.ReportsService.list_reports({ pathPrefix: '/research/' });
+await tools.ReportsService.write_report({ path: '/output.md', content: '...' });
+
+// Delegation
+const teammates = await tools.DelegationService.list_teammates();
+const task = await tools.DelegationService.delegate_task({ teammate: 'dev', task: '...' });
+
+// Batch
+const job = await tools.BatchService.create_batch_job({ name: 'Process', ... });
+
+// Tool Discovery
+const tools = await tools.ToolDiscoveryService.discover_tools();
+```
+
+### expand_trace(input)
+
+Get details for a specific tool call.
+
+```typescript
+const details = await ctx.majk.scripting.expand_trace({
+  traceId: string,
+  callSeq: number  // Sequence number from trace
+});
+// Returns: { call, fullParams, fullResult, functionSchema? }
+```
+
+### list_traces()
+
+List recent script executions.
+
+```typescript
+const { traces, count } = await ctx.majk.scripting.list_traces();
+// traces: Array<{ id, storedAt, summary: { success, totalCalls, durationMs, dryRun } }>
+```
+
+### get_trace_formatted(input)
+
+Get formatted trace output.
+
+```typescript
+const trace = await ctx.majk.scripting.get_trace_formatted({ traceId: string });
+// Returns: { traceFormatted, success, totalCalls, durationMs }
+```
+
+## Dry-Run Mode
+
+Test scripts without making changes:
+
+```typescript
+const result = await ctx.majk.scripting.execute_script({
+  code: `
+    // This won't actually write
+    await tools.ReportsService.write_report({
+      path: '/test.md',
+      content: 'Test content'
+    });
+    return 'done';
+  `,
+  dryRun: true
+});
+
+// Trace shows what WOULD have happened
+console.log(result.traceFormatted);
+```
+
+## Parameterized Scripts
+
+```typescript
+// First run
+const result = await ctx.majk.scripting.execute_script({
+  code: `
+    const reports = await tools.ReportsService.list_reports({
+      pathPrefix: params.prefix,
+      limit: params.limit
+    });
+    return reports;
+  `,
+  params: { prefix: '/research/', limit: 5 }
+});
+
+// Re-run with different params
+const result2 = await ctx.majk.scripting.execute_script({
+  rerun: result.traceId,
+  params: { prefix: '/docs/', limit: 10 }
+});
+```
+
+## Complex Orchestration
+
+```typescript
+const result = await ctx.majk.scripting.execute_script({
+  code: `
+    // Find all TypeScript files
+    const files = await tools.FileSystem.glob({ pattern: 'src/**/*.ts' });
+
+    // Create batch job to analyze them
+    const { job } = await tools.BatchService.create_batch_job({
+      name: 'Analyze TS files',
+      input: { source: { type: 'list', items: files } },
+      processor: { type: 'rpc', functionName: 'analyze_file' },
+      autoStart: true
+    });
+
+    // Wait for completion
+    const result = await tools.BatchService.await_batch_job({ jobId: job.id });
+
+    // Write summary report
+    await tools.ReportsService.write_report({
+      path: '/analysis/summary.md',
+      content: \`# Analysis Summary\\n\\nProcessed \${result.finalProgress.completedItems} files.\`
+    });
+
+    return result.finalProgress;
+  `
+});
+```
+
+## Error Handling
+
+```typescript
+const result = await ctx.majk.scripting.execute_script({
+  code: `
+    try {
+      const data = await tools.SomeService.risky_operation();
+      return { success: true, data };
+    } catch (error) {
+      console.error('Operation failed:', error.message);
+      return { success: false, error: error.message };
+    }
+  `
+});
+
+if (!result.success) {
+  console.log('Script error:', result.error);
+  console.log('Trace:', result.traceFormatted);
+}
+```
+
+## Debugging with Traces
+
+```typescript
+// Execute script
+const result = await ctx.majk.scripting.execute_script({ code: '...' });
+
+// View formatted trace
+console.log(result.traceFormatted);
+
+// Inspect specific call
+const callDetails = await ctx.majk.scripting.expand_trace({
+  traceId: result.traceId,
+  callSeq: 3  // Third tool call
+});
+console.log('Params:', callDetails.fullParams);
+console.log('Result:', callDetails.fullResult);
+```
+
+## Best Practices
+
+1. **Use dry-run first** - Test scripts before real execution
+2. **Add error handling** - Wrap risky operations in try/catch
+3. **Use parameters** - Make scripts reusable
+4. **Check traces** - Debug issues with trace inspection
+5. **Keep scripts focused** - One clear purpose per script
+
+## Next Steps
+
+Run `npx @majkapp/plugin-kit --tool-discovery` - Discover available tools
+Run `npx @majkapp/plugin-kit --batch` - Batch processing API
+Run `npx @majkapp/plugin-kit --delegation` - Task delegation API