Getting Started

# Clone the repository
git clone https://github.com/aliquanhou/tll-os.git
cd tll-os

# Install dependencies
npm install

# Verify installation
npx tsc --noEmit
→ No errors (zero dependencies runtime)

import { createTllOS } from '@tll/os/public';

const app = createTllOS({
  name: 'my-first-app',
  version: '0.1.0',
  description: 'My first TLL OS application'
});

// The Application Graph is automatically created
console.log('Application created:', app.getName());
console.log('Graph nodes:', app.getGraph().listNodes().length);

const helloModule = app.registerModule({
  name: 'hello',
  version: '1.0.0',
  description: 'A simple greeting module'
});

// Modules automatically appear in the Application Graph
// Graph now has: module:hello node + belongs_to edge to application

helloModule.registerApi({
  method: 'GET',
  path: '/api/hello',
  description: 'Return a greeting message',
  handler: async (req) => {
    return { message: 'Hello, TLL OS!' };
  }
});

helloModule.registerApi({
  method: 'GET',
  path: '/api/hello/:name',
  description: 'Greet a specific person',
  handler: async (req) => {
    const name = req.params.name;
    return { message: `Hello, ${name}!` };
  }
});

// Test the API
const response = await app.request('GET', '/api/hello/World');
console.log(response.body); // { message: 'Hello, World!' }

helloModule.registerTool({
  name: 'greet',
  description: 'Generate a personalized greeting',
  parameters: {
    name: { type: 'string', required: true, description: 'Person to greet' },
    language: { type: 'string', required: false, default: 'en', description: 'Language code' }
  },
  execute: async (params) => {
    const greetings: Record = {
      en: 'Hello', es: 'Hola', zh: '你好', fr: 'Bonjour'
    };
    const greeting = greetings[params.language] || greetings.en;
    return { message: `${greeting}, ${params.name}!` };
  }
});

// Agents can discover and call this tool
const tools = app.listTools();
console.log(tools.map(t => t.name)); // ['greet']

const greeterAgent = app.registerAgent({
  name: 'greeter',
  description: 'An agent that greets people in multiple languages',
  tools: ['greet'],  // Tools this agent can use
  handler: async (input, context) => {
    // Simple intent: "greet Alice in Spanish"
    const match = input.match(/greet (\w+)(?: in (\w+))?/i);
    if (match) {
      const result = await context.callTool('greet', {
        name: match[1],
        language: match[2] || 'en'
      });
      return result;
    }
    return { error: 'I can only greet people. Try: "greet Alice in Spanish"' };
  }
});

// Use the agent
const result = await greeterAgent.run('greet Alice in Spanish');
console.log(result); // { message: 'Hola, Alice!' }

helloModule.registerTest({
  name: 'api.hello_returns_greeting',
  run: async (app) => {
    const res = await app.request('GET', '/api/hello');
    if (res.status !== 200) throw new Error('Expected 200');
    if (res.body.message !== 'Hello, TLL OS!') throw new Error('Wrong message');
  }
});

helloModule.registerTest({
  name: 'api.hello_with_name',
  run: async (app) => {
    const res = await app.request('GET', '/api/hello/World');
    if (res.body.message !== 'Hello, World!') throw new Error('Wrong message');
  }
});

// Run all tests
const results = await app.runTests();
console.log(`${results.passed}/${results.total} passed`);
// → 2/2 passed

# Run your application
npx tsx src/app.ts

# Or use the CLI (Runtime 0.2+)
tll serve
→ TLL OS running at http://localhost:3000
→ GET /api/hello → { "message": "Hello, TLL OS!" }
→ GET /api/hello/World → { "message": "Hello, World!" }

const graph = app.getGraph();

// List all nodes
console.log('Nodes:', graph.listNodes().map(n => `${n.type}:${n.name}`));
// → ['application:my-first-app', 'module:hello', 'api:GET /api/hello', ...]

// List all edges
console.log('Edges:', graph.listEdges().map(e => `${e.from} --${e.type}--> ${e.to}`));
// → ['module:hello --belongs_to--> application:my-first-app', ...]

// Find all APIs in a module
const apis = graph.findNodes({ type: 'api', belongsTo: 'module:hello' });
console.log('Hello module APIs:', apis.map(a => a.name));

// Impact analysis: what depends on this module?
const impact = graph.getImpactAnalysis('module:hello');
console.log('Affected by removing hello module:', impact.affected);

// Runtime 0.2+ will include the Shopify Adapter
// For now, this shows the intended API

// const shopify = app.installAdapter('shopify', {
//   store: 'mystore.myshopify.com',
//   token: 'shpat_xxx'
// });
//
// await shopify.connect();
// → Synced 142 products into Application Graph
//
// const products = graph.findNodes({ type: 'model', name: 'Product' });
// console.log('Products from Shopify:', products.length);

# Build for web (Runtime 0.2+)
tll build --target web
→ dist/web/

# Build for AI Agent (MCP Server)
tll build --target ai_agent
→ dist/agent/

# Build for desktop
tll build --target exe
→ dist/desktop/