@agents-at-scale/ark 0.1.36 → 0.1.38

package/dist/lib/waitForReady.js

@@ -0,0 +1,32 @@
+import { execa } from 'execa';
+export async function waitForDeploymentReady(deploymentName, namespace, timeoutSeconds) {
+    try {
+        await execa('kubectl', [
+            'wait',
+            '--for=condition=available',
+            `deployment/${deploymentName}`,
+            '-n',
+            namespace,
+            `--timeout=${timeoutSeconds}s`,
+        ], { timeout: timeoutSeconds * 1000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function waitForServicesReady(services, timeoutSeconds, onProgress) {
+    const validServices = services.filter((s) => s.k8sDeploymentName && s.namespace);
+    const checkPromises = validServices.map(async (service) => {
+        const isReady = await waitForDeploymentReady(service.k8sDeploymentName, service.namespace, timeoutSeconds);
+        if (onProgress) {
+            onProgress({
+                serviceName: service.name,
+                ready: isReady,
+            });
+        }
+        return isReady;
+    });
+    const results = await Promise.all(checkPromises);
+    return results.every((ready) => ready);
+}

package/dist/lib/waitForReady.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/waitForReady.spec.js

@@ -0,0 +1,104 @@
+import { describe, it, expect, jest, beforeEach } from '@jest/globals';
+jest.unstable_mockModule('execa', () => ({
+    execa: jest.fn(),
+}));
+const { execa } = await import('execa');
+const { waitForDeploymentReady, waitForServicesReady } = await import('./waitForReady.js');
+const mockedExeca = execa;
+describe('waitForDeploymentReady', () => {
+    beforeEach(() => {
+        jest.clearAllMocks();
+    });
+    it('returns true when deployment is ready', async () => {
+        mockedExeca.mockResolvedValueOnce({
+            stdout: 'deployment.apps/ark-controller condition met',
+            stderr: '',
+            exitCode: 0,
+        });
+        const result = await waitForDeploymentReady('ark-controller', 'ark-system', 30);
+        expect(result).toBe(true);
+        expect(mockedExeca).toHaveBeenCalledWith('kubectl', [
+            'wait',
+            '--for=condition=available',
+            'deployment/ark-controller',
+            '-n',
+            'ark-system',
+            '--timeout=30s',
+        ], { timeout: 30000 });
+    });
+    it('returns false on error', async () => {
+        mockedExeca.mockRejectedValueOnce(new Error('kubectl error'));
+        const result = await waitForDeploymentReady('ark-api', 'default', 10);
+        expect(result).toBe(false);
+    });
+});
+describe('waitForServicesReady', () => {
+    beforeEach(() => {
+        jest.clearAllMocks();
+    });
+    const service1 = {
+        name: 'ark-controller',
+        helmReleaseName: 'ark-controller',
+        description: 'Core controller',
+        enabled: true,
+        category: 'core',
+        namespace: 'ark-system',
+        k8sDeploymentName: 'ark-controller',
+    };
+    const service2 = {
+        name: 'ark-api',
+        helmReleaseName: 'ark-api',
+        description: 'API service',
+        enabled: true,
+        category: 'service',
+        namespace: 'default',
+        k8sDeploymentName: 'ark-api',
+    };
+    it('returns true when all services are ready', async () => {
+        mockedExeca.mockResolvedValue({
+            stdout: 'condition met',
+            stderr: '',
+            exitCode: 0,
+        });
+        const result = await waitForServicesReady([service1, service2], 30);
+        expect(result).toBe(true);
+        expect(mockedExeca).toHaveBeenCalledTimes(2);
+    });
+    it('returns false when any service fails', async () => {
+        mockedExeca
+            .mockResolvedValueOnce({ stdout: 'ok', stderr: '', exitCode: 0 })
+            .mockRejectedValueOnce(new Error('timeout'));
+        const result = await waitForServicesReady([service1, service2], 30);
+        expect(result).toBe(false);
+    });
+    it('calls progress callback', async () => {
+        mockedExeca.mockResolvedValue({
+            stdout: 'ok',
+            stderr: '',
+            exitCode: 0,
+        });
+        const onProgress = jest.fn();
+        await waitForServicesReady([service1], 30, onProgress);
+        expect(onProgress).toHaveBeenCalledWith({
+            serviceName: 'ark-controller',
+            ready: true,
+        });
+    });
+    it('skips services without deployment info', async () => {
+        const incompleteService = {
+            name: 'incomplete',
+            helmReleaseName: 'incomplete',
+            description: 'No deployment info',
+            enabled: true,
+            category: 'service',
+        };
+        mockedExeca.mockResolvedValue({
+            stdout: 'ok',
+            stderr: '',
+            exitCode: 0,
+        });
+        const result = await waitForServicesReady([service1, incompleteService], 30);
+        expect(result).toBe(true);
+        expect(mockedExeca).toHaveBeenCalledTimes(1);
+    });
+});

package/dist/types/arkService.d.ts

@@ -0,0 +1,27 @@
+export interface ArkService {
+    name: string;
+    helmReleaseName: string;
+    description: string;
+    enabled: boolean;
+    category: string;
+    namespace?: string;
+    chartPath?: string;
+    installArgs?: string[];
+    k8sServiceName?: string;
+    k8sServicePort?: number;
+    k8sPortForwardLocalPort?: number;
+    k8sDeploymentName?: string;
+    k8sDevDeploymentName?: string;
+}
+export interface ServiceCollection {
+    [key: string]: ArkService;
+}
+export interface ArkDependency {
+    name: string;
+    command: string;
+    args: string[];
+    description: string;
+}
+export interface DependencyCollection {
+    [key: string]: ArkDependency;
+}

package/dist/types/arkService.js

@@ -0,0 +1 @@
+export {};

package/dist/ui/asyncOperations/connectingToArk.d.ts

@@ -0,0 +1,15 @@
+import { AsyncOperationConfig } from '../../components/AsyncOperation.js';
+import { ArkApiClient } from '../../lib/arkApiClient.js';
+import { ChatClient, QueryTarget } from '../../lib/chatClient.js';
+export interface ConnectingToArkParams {
+    arkApiClient: ArkApiClient;
+    initialTargetId?: string;
+    onSuccess: (data: {
+        client: ChatClient;
+        targets: QueryTarget[];
+        selectedTarget: QueryTarget | null;
+        selectedIndex: number;
+    }) => void;
+    onQuit: () => void;
+}
+export declare function createConnectingToArkOperation(params: ConnectingToArkParams): AsyncOperationConfig;

package/dist/ui/asyncOperations/connectingToArk.js

@@ -0,0 +1,63 @@
+import { ChatClient } from '../../lib/chatClient.js';
+export function createConnectingToArkOperation(params) {
+    return {
+        message: 'Connecting to Ark...',
+        operation: async (_signal) => {
+            const client = new ChatClient(params.arkApiClient);
+            const targets = await client.getQueryTargets();
+            let selectedTarget = null;
+            let selectedIndex = 0;
+            if (params.initialTargetId) {
+                const matchedTarget = targets.find((t) => t.id === params.initialTargetId);
+                const matchedIndex = targets.findIndex((t) => t.id === params.initialTargetId);
+                if (matchedTarget) {
+                    selectedTarget = matchedTarget;
+                    selectedIndex = matchedIndex >= 0 ? matchedIndex : 0;
+                }
+                else {
+                    throw new Error(`Target "${params.initialTargetId}" not found. Use "ark targets list" to see available targets.`);
+                }
+            }
+            else if (targets.length > 0) {
+                const agents = targets.filter((t) => t.type === 'agent');
+                const models = targets.filter((t) => t.type === 'model');
+                const tools = targets.filter((t) => t.type === 'tool');
+                if (agents.length > 0) {
+                    selectedTarget = agents[0];
+                    selectedIndex = targets.findIndex((t) => t.id === agents[0].id);
+                }
+                else if (models.length > 0) {
+                    selectedTarget = models[0];
+                    selectedIndex = targets.findIndex((t) => t.id === models[0].id);
+                }
+                else if (tools.length > 0) {
+                    selectedTarget = tools[0];
+                    selectedIndex = targets.findIndex((t) => t.id === tools[0].id);
+                }
+                else {
+                    throw new Error('No targets available');
+                }
+            }
+            else {
+                throw new Error('No agents, models, or tools available');
+            }
+            params.onSuccess({
+                client,
+                targets,
+                selectedTarget,
+                selectedIndex,
+            });
+        },
+        hideOnSuccess: true,
+        errorOptions: [
+            { label: 'Try again', onSelect: () => { } },
+            {
+                label: 'Check status',
+                onSelect: () => {
+                    console.log('Status command not yet implemented');
+                },
+            },
+            { label: 'Quit', onSelect: params.onQuit },
+        ],
+    };
+}

package/package.json

@@ -1,24 +1,26 @@
 {
   "name": "@agents-at-scale/ark",
-  "version": "0.1.36",
-  "description": "ARK CLI - Interactive terminal interface for ARK agents",
+  "version": "0.1.38",
+  "description": "Ark CLI - Interactive terminal interface for ARK agents",
   "main": "dist/index.js",
   "type": "module",
   "bin": {
     "ark": "dist/index.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "templates"
   ],
   "scripts": {
-    "build": "tsc && chmod +x dist/index.js",
+    "build": "npm run copy-templates && tsc && chmod +x dist/index.js",
+    "copy-templates": "rm -rf templates && cp -r ../../templates .",
     "dev": "tsc --watch",
     "start": "NODE_NO_WARNINGS=1 node dist/index.js",
     "clean": "rm -rf dist",
     "lint": "eslint src/ --fix && prettier --write src/",
     "lint:check": "eslint src/ && prettier --check src/",
     "test": "NODE_OPTIONS=\"--experimental-vm-modules\" jest --coverage --coverageDirectory=./artifacts/coverage --coverageReporters=text --coverageReporters=lcov --coverageReporters=text-summary",
-    "postinstall": "echo \"ARK CLI installed! Run 'ark' to try it out.\""
+    "postinstall": "echo \"Ark CLI installed. Run 'ark' to try it out.\""
   },
   "keywords": [
     "ark",

package/templates/agent/agent.template.yaml

@@ -0,0 +1,27 @@
+apiVersion: ark.mckinsey.com/v1alpha1
+kind: Agent
+metadata:
+  name: {{ .Values.agentName }}-agent
+  labels:
+    project: {{ .Values.projectName }}
+    role: assistant
+    tier: basic
+spec:
+  description: {{ .Values.agentName }} agent for {{ .Values.projectName }} project
+  prompt: |
+    You are a helpful AI assistant for the {{ .Values.projectName }} project. You provide clear, concise, and accurate responses to user questions.
+
+    Key guidelines:
+    - Be direct and to the point
+    - Use simple language when possible
+    - If you don't know something, say so
+    - Always be polite and professional
+
+  # Reference to model (will be created by Helm chart)
+  modelRef:
+    name: default
+
+  # Optional: Add built-in tools
+  tools:
+    - type: built-in
+      name: terminate

package/templates/marketplace/.editorconfig

@@ -0,0 +1,24 @@
+# EditorConfig is awesome: https://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false
+
+[Makefile]
+indent_style = tab
+
+[*.py]
+indent_size = 4
+
+[*.go]
+indent_style = tab

package/templates/marketplace/.github/.keep

@@ -0,0 +1,11 @@
+# GitHub Configuration Directory
+
+GitHub-specific configuration files for the marketplace repository.
+
+Expected contents:
+- workflows/ - GitHub Actions workflows
+- ISSUE_TEMPLATE/ - Issue templates
+- PULL_REQUEST_TEMPLATE.md - PR template
+- CODEOWNERS - Code ownership rules
+
+These files help maintain quality and consistency in contributions.

package/templates/marketplace/.github/workflows/.keep

@@ -0,0 +1,16 @@
+# GitHub Workflows Directory
+
+GitHub Actions workflows for automating marketplace operations.
+
+Common workflows:
+- component-validation.yml - Validate contributed components
+- security-scan.yml - Security scanning of components
+- documentation-build.yml - Build and deploy documentation
+- release.yml - Automated releases
+- pr-checks.yml - Pull request validation
+
+Workflows should:
+- Be efficient and reliable
+- Provide clear feedback
+- Follow security best practices
+- Be well-documented

package/templates/marketplace/.helmignore

@@ -0,0 +1,23 @@
+# Patterns to ignore when building packages.
+# This supports shell glob matching, relative path matching, and
+# negation (prefixed with !). Only one pattern per line.
+.DS_Store
+# Common VCS dirs
+.git/
+.gitignore
+.bzr/
+.bzrignore
+.hg/
+.hgignore
+.svn/
+# Common backup files
+*.swp
+*.bak
+*.tmp
+*.orig
+*~
+# Various IDEs
+.project
+.idea/
+*.tmproj
+.vscode/

package/templates/marketplace/.prettierrc.json

@@ -0,0 +1,20 @@
+{
+  "semi": true,
+  "trailingComma": "es5",
+  "singleQuote": true,
+  "printWidth": 80,
+  "tabWidth": 2,
+  "useTabs": false,
+  "arrowParens": "avoid",
+  "bracketSpacing": true,
+  "proseWrap": "preserve",
+  "quoteProps": "as-needed",
+  "overrides": [
+    {
+      "files": "*.yaml",
+      "options": {
+        "singleQuote": false
+      }
+    }
+  ]
+}

package/templates/marketplace/.yamllint.yml

@@ -0,0 +1,53 @@
+# Default rules for yamllint
+extends: default
+
+rules:
+  # 120 chars should be enough, but don't fail if a line is longer
+  line-length:
+    max: 120
+    level: warning
+
+  # accept both       key:value and key: value
+  colons:
+    max-spaces-before: 0
+    max-spaces-after: -1
+
+  # don't bother me with tabs vs spaces issues
+  indentation:
+    spaces: consistent
+    indent-sequences: whatever
+
+  # allow empty values like 'key:'
+  empty-values:
+    forbid-in-block-mappings: false
+    forbid-in-flow-mappings: false
+
+  # sometimes you have to use quotes
+  quoted-strings:
+    quote-type: any
+    required: false
+
+  # allow trailing spaces in comments
+  trailing-spaces:
+    level: warning
+
+  # allow truthy values
+  truthy:
+    allowed-values: ['true', 'false', 'on', 'off', 'yes', 'no']
+    check-keys: false
+
+  # allow ! in yaml
+  comments:
+    require-starting-space: false
+    ignore-shebangs: true
+    min-spaces-from-content: 1
+
+  # brackets
+  brackets:
+    max-spaces-inside: 1
+    max-spaces-inside-empty: 0
+
+  # braces
+  braces:
+    max-spaces-inside: 1
+    max-spaces-inside-empty: 0

package/templates/marketplace/README.md

@@ -0,0 +1,197 @@
+# ARK Marketplace
+
+Welcome to the ARK Marketplace - a central repository for sharing reusable ARK components across projects and teams.
+
+## Overview
+
+The marketplace serves as a community-driven collection of:
+
+- **Agents** - Pre-configured AI agents for specific tasks
+- **Teams** - Multi-agent workflows and orchestration patterns
+- **Models** - Model configurations for different providers and use cases
+- **Tools** - Extensions that add capabilities to agents
+- **MCP Servers** - Model Context Protocol server implementations
+- **Queries** - Reusable query templates and patterns
+- **Projects** - Complete, end-to-end Ark project templates and solutions
+
+## Repository Structure
+
+```
+marketplace/
+├── agents/           # Reusable agent definitions
+├── teams/            # Multi-agent workflow configurations
+├── models/           # Model configurations by provider
+├── queries/          # Query templates and patterns
+├── tools/            # Tool definitions and implementations
+├── mcp-servers/      # MCP server configurations
+├── projects/         # Complete Ark project templates and solutions
+├── tests/            # Test configurations and utilities
+├── scripts/          # Automation and validation scripts
+├── docs/             # Documentation and guides
+├── templates/        # Component creation templates
+└── .github/          # GitHub workflows and templates
+```
+
+## Contributing Components
+
+### Getting Started
+
+1. **Fork** this repository
+2. **Choose** the appropriate directory for your component type
+3. **Copy** the relevant template from `templates/` directory
+4. **Implement** your component following the guidelines
+5. **Test** your component thoroughly
+6. **Submit** a pull request
+
+### Component Guidelines
+
+#### Agents (`agents/`)
+
+- One agent per subdirectory
+- Include `agent.yaml` with complete agent definition
+- Provide comprehensive `README.md` with usage examples
+- Test with multiple model providers when possible
+
+#### Teams (`teams/`)
+
+- Document the workflow strategy and use cases
+- Include example inputs and expected outputs
+- Explain when to use this team configuration
+- Test the complete workflow end-to-end
+
+#### Models (`models/`)
+
+- Organize by provider (openai/, anthropic/, etc.)
+- Include provider-specific configurations
+- Document capabilities, limitations, and costs
+- Specify recommended use cases
+
+#### Tools (`tools/`)
+
+- Follow Ark tool specification
+- Include source code and build instructions
+- Provide security considerations
+- Include comprehensive error handling
+
+#### MCP Servers (`mcp-servers/`)
+
+- Follow MCP protocol specifications
+- Document all available tools and resources
+- Include security and monitoring configurations
+- Provide integration examples
+
+#### Queries (`queries/`)
+
+- Make queries parameterizable where possible
+- Document expected inputs and outputs
+- Specify compatible agents and teams
+- Include usage examples
+
+#### Projects (`projects/`)
+
+- Provide complete, self-contained Ark project structures
+- Include comprehensive documentation with architecture overview
+- Specify all required dependencies (models, tools, external services)
+- Provide clear setup and deployment instructions
+- Include working examples and sample data where applicable
+- Document the use case and target scenarios
+- Follow Ark best practices for resource organization
+- Include multiple components working together (agents, teams, tools, etc.)
+
+### Quality Standards
+
+All contributions must meet these standards:
+
+- ✅ **Documentation** - Clear README with setup and usage instructions
+- ✅ **Security** - Follow security best practices
+- ✅ **Compatibility** - Work with latest Ark version
+- ✅ **Examples** - Provide working usage examples
+- ✅ **Validation** - Pass all automated validation checks
+
+### Submission Process
+
+1. **Create** your component following the guidelines above
+2. **Run** validation scripts: `scripts/validate-component.sh <component-path>`
+3. **Test** your component in a real environment
+4. **Submit** pull request with:
+   - Clear description of the component's purpose
+   - Usage examples and test results
+   - Documentation of any dependencies
+   - Screenshots or demos if applicable
+
+### Review Process
+
+1. **Automated Checks** - CI pipeline validates component structure and security
+2. **Community Review** - Other contributors provide feedback
+3. **Maintainer Review** - Core team performs final review
+4. **Approval** - Component is merged and becomes available
+
+## Using Marketplace Components
+
+### Finding Components
+
+- Browse directories by component type
+- Check `README.md` files for detailed descriptions
+- Look for tags and categories in component metadata
+- Use GitHub search to find specific functionality
+
+### Installing Components
+
+1. **Copy** the component files to your project
+2. **Customize** configuration as needed
+3. **Install** any dependencies listed in component README
+4. **Test** the component in your environment
+5. **Deploy** following your project's deployment process
+
+### Component Versioning
+
+Components follow semantic versioning:
+
+- **Major** - Breaking changes requiring migration
+- **Minor** - New features, backward compatible
+- **Patch** - Bug fixes and minor improvements
+
+## Support and Community
+
+### Getting Help
+
+- 📖 **Documentation** - Check `docs/` directory for guides
+- 💬 **Discussions** - Use GitHub Discussions for questions
+- 🐛 **Issues** - Report bugs or request features via GitHub Issues
+- 📧 **Contact** - Reach out to maintainers for urgent matters
+
+### Contributing Beyond Components
+
+We welcome contributions in many forms:
+
+- 📝 **Documentation** improvements
+- 🧪 **Testing** and validation improvements
+- 🔧 **Tooling** and automation enhancements
+- 🎨 **Templates** and examples
+- 🔍 **Reviews** and feedback on submissions
+
+## Governance
+
+### Maintainers
+
+The marketplace is maintained by the core team and trusted community contributors.
+
+### Licensing
+
+All contributions must be compatible with the project license. By contributing, you agree to license your contributions under the same terms.
+
+### Code of Conduct
+
+This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md). Please read and follow these guidelines in all interactions.
+
+## Quick Start
+
+Ready to contribute? Start here:
+
+1. **Explore** existing components for inspiration
+2. **Choose** a template from `templates/` directory
+3. **Read** the component-specific guidelines in `docs/`
+4. **Create** your component following the standards
+5. **Submit** your pull request
+
+Thank you for contributing to the {{ .Values.projectName }} Marketplace! 🚀