clawcontainer 1.0.0

package/src/templates.ts

@@ -0,0 +1,271 @@
+// ─── Template System for ClawContainer ──────────────────────────────────────
+
+import type { AgentConfig, ClawContainerOptions, TabDefinition } from './types.js';
+
+/** A named, reusable container configuration preset. */
+export interface ContainerTemplate {
+  name: string;
+  description?: string;
+  agent?: AgentConfig | false;
+  workspace?: Record<string, string>;
+  services?: Record<string, string>;
+  env?: Record<string, string>;
+  startupScript?: string;
+  tabs?: TabDefinition[];
+}
+
+/** Built-in gitclaw template — mirrors the previous hardcoded defaults. */
+export const GITCLAW_TEMPLATE: ContainerTemplate = {
+  name: 'gitclaw',
+  description: 'Default gitclaw agent template',
+  agent: {
+    package: 'gitclaw',
+    version: '1.1.4',
+    entry: 'dist/index.js',
+    args: ['--dir', '<home>/workspace'],
+  },
+};
+
+// ─── Template Registry ────────────────────────────────────────────────────────
+
+export class TemplateRegistry {
+  private templates = new Map<string, ContainerTemplate>();
+
+  constructor() {
+    // Seed with built-in templates
+    this.register(GITCLAW_TEMPLATE);
+  }
+
+  register(template: ContainerTemplate): void {
+    this.templates.set(template.name, template);
+  }
+
+  get(name: string): ContainerTemplate | undefined {
+    return this.templates.get(name);
+  }
+
+  has(name: string): boolean {
+    return this.templates.has(name);
+  }
+
+  list(): string[] {
+    return [...this.templates.keys()];
+  }
+
+  /** Expose the internal map (read-only use). */
+  get all(): Map<string, ContainerTemplate> {
+    return this.templates;
+  }
+}
+
+// ─── Resolution & merging ─────────────────────────────────────────────────────
+
+/**
+ * Resolve a template input to a concrete ContainerTemplate.
+ * - string → lookup by name in registry
+ * - object → use directly
+ * - undefined → default to 'gitclaw'
+ */
+export function resolveTemplate(
+  input: string | ContainerTemplate | undefined,
+  registry: TemplateRegistry,
+): ContainerTemplate {
+  if (input === undefined) {
+    return registry.get('gitclaw')!;
+  }
+  if (typeof input === 'string') {
+    const tpl = registry.get(input);
+    if (!tpl) throw new Error(`Unknown template: "${input}". Registered: ${registry.list().join(', ')}`);
+    return tpl;
+  }
+  return input;
+}
+
+/**
+ * Merge a resolved template with user-supplied ClawContainerOptions.
+ * Options win for conflicts. Record fields (workspace, services, env) are merged per-key.
+ * Scalar fields (agent, startupScript) are replaced when present in options.
+ */
+export function mergeTemplateWithOptions(
+  template: ContainerTemplate,
+  options: ClawContainerOptions,
+): ClawContainerOptions {
+  const merged: ClawContainerOptions = {};
+
+  // Agent: options.agent takes precedence if explicitly set (including false)
+  if (options.agent !== undefined) {
+    merged.agent = options.agent;
+  } else if (template.agent !== undefined) {
+    merged.agent = template.agent;
+  }
+
+  // Record fields: template first, options overlay
+  merged.workspace = { ...template.workspace, ...options.workspace };
+  merged.services = { ...template.services, ...options.services };
+  merged.env = { ...template.env, ...options.env };
+
+  // Scalar: options win
+  merged.startupScript = options.startupScript ?? template.startupScript;
+
+  // Tabs: concat template tabs + options tabs (dedup by id, options win)
+  const templateTabs = template.tabs ?? [];
+  const optionTabs = options.tabs ?? [];
+  if (templateTabs.length > 0 || optionTabs.length > 0) {
+    const tabMap = new Map<string, TabDefinition>();
+    for (const t of templateTabs) tabMap.set(t.id, t);
+    for (const t of optionTabs) tabMap.set(t.id, t);
+    merged.tabs = [...tabMap.values()];
+  }
+
+  // Pass through non-template fields
+  if (options.plugins) merged.plugins = options.plugins;
+
+  return merged;
+}
+
+// ─── YAML Parsing (hand-rolled, no deps) ──────────────────────────────────────
+
+/**
+ * Parse a YAML string into a ContainerTemplate.
+ * Supports the simple subset needed for template definitions:
+ * - Top-level scalar keys (name, description, startupScript)
+ * - Top-level `agent:` with nested scalar keys + args/env
+ * - Top-level Record sections (workspace, services, env)
+ * - `agent: false` to skip agent launch
+ */
+export function parseTemplateYaml(yaml: string): ContainerTemplate {
+  const lines = yaml.split('\n');
+  const template: ContainerTemplate = { name: '' };
+
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    const trimmed = line.trim();
+
+    // Skip blank lines and comments
+    if (trimmed === '' || trimmed.startsWith('#')) { i++; continue; }
+
+    // Top-level key: value
+    const kvMatch = trimmed.match(/^(\w+):\s*(.*)$/);
+    if (!kvMatch) { i++; continue; }
+
+    const key = kvMatch[1];
+    const value = kvMatch[2].trim();
+
+    if (key === 'name') {
+      template.name = stripQuotes(value);
+      i++;
+    } else if (key === 'description') {
+      template.description = stripQuotes(value);
+      i++;
+    } else if (key === 'startupScript') {
+      template.startupScript = stripQuotes(value);
+      i++;
+    } else if (key === 'agent') {
+      if (value === 'false') {
+        template.agent = false;
+        i++;
+      } else if (value === '' || value === undefined) {
+        // Nested agent block
+        const agent: AgentConfig = { package: '', entry: '' };
+        i++;
+        while (i < lines.length) {
+          const aLine = lines[i];
+          const aTrimmed = aLine.trim();
+          if (aTrimmed === '' || aTrimmed.startsWith('#')) { i++; continue; }
+          // Check if we've left the agent block (no leading whitespace)
+          if (/^\S/.test(aLine)) break;
+
+          const aKv = aTrimmed.match(/^(\w+):\s*(.*)$/);
+          if (!aKv) { i++; continue; }
+
+          const aKey = aKv[1];
+          const aVal = aKv[2].trim();
+
+          if (aKey === 'package') { agent.package = stripQuotes(aVal); i++; }
+          else if (aKey === 'version') { agent.version = stripQuotes(aVal); i++; }
+          else if (aKey === 'entry') { agent.entry = stripQuotes(aVal); i++; }
+          else if (aKey === 'args') {
+            agent.args = parseYamlInlineArray(aVal);
+            i++;
+          } else if (aKey === 'env') {
+            // Nested env block under agent
+            agent.env = {};
+            i++;
+            while (i < lines.length) {
+              const eLine = lines[i];
+              const eTrimmed = eLine.trim();
+              if (eTrimmed === '' || eTrimmed.startsWith('#')) { i++; continue; }
+              // Must be indented deeper than agent keys (at least 4 spaces)
+              const indent = eLine.length - eLine.trimStart().length;
+              if (indent < 4) break;
+              const eKv = eTrimmed.match(/^(\w+):\s*(.*)$/);
+              if (eKv) {
+                agent.env[eKv[1]] = stripQuotes(eKv[2].trim());
+              }
+              i++;
+            }
+          } else { i++; }
+        }
+        template.agent = agent;
+      } else { i++; }
+    } else if (key === 'workspace' || key === 'services' || key === 'env') {
+      const record: Record<string, string> = {};
+      i++;
+      while (i < lines.length) {
+        const rLine = lines[i];
+        const rTrimmed = rLine.trim();
+        if (rTrimmed === '' || rTrimmed.startsWith('#')) { i++; continue; }
+        if (/^\S/.test(rLine)) break;
+
+        // key: value or key: | (block scalar)
+        const rKv = rTrimmed.match(/^(.+?):\s*(.*)$/);
+        if (!rKv) { i++; continue; }
+
+        const rKey = rKv[1].trim();
+        const rVal = rKv[2].trim();
+
+        if (rVal === '|') {
+          // Block scalar — collect indented lines
+          i++;
+          const blockLines: string[] = [];
+          const baseIndent = i < lines.length ? (lines[i].length - lines[i].trimStart().length) : 4;
+          while (i < lines.length) {
+            const bLine = lines[i];
+            if (bLine.trim() === '') { blockLines.push(''); i++; continue; }
+            const bIndent = bLine.length - bLine.trimStart().length;
+            if (bIndent < baseIndent) break;
+            blockLines.push(bLine.slice(baseIndent));
+            i++;
+          }
+          record[rKey] = blockLines.join('\n') + '\n';
+        } else {
+          record[rKey] = stripQuotes(rVal);
+          i++;
+        }
+      }
+      (template as any)[key] = record;
+    } else {
+      i++;
+    }
+  }
+
+  if (!template.name) throw new Error('Template YAML must include a "name" field');
+  return template;
+}
+
+/** Strip surrounding quotes from a YAML value. */
+function stripQuotes(s: string): string {
+  if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) {
+    return s.slice(1, -1);
+  }
+  return s;
+}
+
+/** Parse a YAML inline array like ["--dir", "<home>/workspace"] */
+function parseYamlInlineArray(s: string): string[] {
+  const trimmed = s.trim();
+  if (!trimmed.startsWith('[') || !trimmed.endsWith(']')) return [];
+  const inner = trimmed.slice(1, -1);
+  return inner.split(',').map(item => stripQuotes(item.trim())).filter(Boolean);
+}

package/src/terminal.ts

@@ -0,0 +1,78 @@
+import { Terminal } from '@xterm/xterm';
+import { FitAddon } from '@xterm/addon-fit';
+
+export class TerminalManager {
+  readonly xterm: Terminal;
+  private readonly fitAddon: FitAddon;
+  private resizeObserver: ResizeObserver | null = null;
+
+  constructor() {
+    this.xterm = new Terminal({
+      convertEol: true,
+      cursorBlink: true,
+      fontSize: 13,
+      fontFamily: "'SF Mono', 'Fira Code', 'Cascadia Code', Menlo, monospace",
+      theme: {
+        background:  '#0d1117',
+        foreground:  '#e6edf3',
+        cursor:      '#f78166',
+        selectionBackground: '#264f78',
+        black:       '#484f58',
+        brightBlack: '#6e7681',
+        red:         '#ff7b72',
+        brightRed:   '#ffa198',
+        green:       '#3fb950',
+        brightGreen: '#56d364',
+        yellow:      '#d29922',
+        brightYellow:'#e3b341',
+        blue:        '#58a6ff',
+        brightBlue:  '#79c0ff',
+        magenta:     '#bc8cff',
+        brightMagenta:'#d2a8ff',
+        cyan:        '#39c5cf',
+        brightCyan:  '#56d4dd',
+        white:       '#b1bac4',
+        brightWhite: '#f0f6fc',
+      },
+      scrollback: 5000,
+    });
+
+    this.fitAddon = new FitAddon();
+    this.xterm.loadAddon(this.fitAddon);
+  }
+
+  /** Mount the terminal into a DOM element and start auto-resize. */
+  mount(container: HTMLElement): void {
+    this.xterm.open(container);
+    this.fitAddon.fit();
+
+    this.resizeObserver = new ResizeObserver(() => {
+      try { this.fitAddon.fit(); } catch { /* ignore */ }
+    });
+    this.resizeObserver.observe(container);
+
+    window.addEventListener('resize', () => {
+      try { this.fitAddon.fit(); } catch { /* ignore */ }
+    });
+  }
+
+  /** Write text/bytes to the terminal display (not to stdin). */
+  write(data: string | Uint8Array): void {
+    this.xterm.write(data);
+  }
+
+  /** Register a handler for user keystrokes (sent to shell stdin). */
+  onData(handler: (data: string) => void): void {
+    this.xterm.onData(handler);
+  }
+
+  /** Current terminal dimensions for pty resize. */
+  get dimensions(): { cols: number; rows: number } {
+    return { cols: this.xterm.cols, rows: this.xterm.rows };
+  }
+
+  dispose(): void {
+    this.resizeObserver?.disconnect();
+    this.xterm.dispose();
+  }
+}

package/src/types.ts

@@ -0,0 +1,113 @@
+// ─── ClawContainer SDK Types ────────────────────────────────────────────────
+
+import type { WebContainer } from '@webcontainer/api';
+import type { AuditEntry, AuditSource, AuditLevel, AuditEvent } from './audit.js';
+import type { ContainerTemplate } from './templates.js';
+
+/** Configuration for launching an agent inside the container. */
+export interface AgentConfig {
+  /** npm package name (e.g. 'gitclaw') */
+  package: string;
+  /** Package version (e.g. '1.1.4'). Defaults to 'latest'. */
+  version?: string;
+  /** Entry file relative to the package directory (e.g. 'dist/index.js') */
+  entry: string;
+  /** Extra CLI args passed to node */
+  args?: string[];
+  /** Extra environment variables for the agent process */
+  env?: Record<string, string>;
+}
+
+/** Options for creating a ClawContainer instance. */
+export interface ClawContainerOptions {
+  /** Agent to launch. Pass `false` to skip agent launch entirely. Default: gitclaw. */
+  agent?: AgentConfig | false;
+  /** Extra workspace files to mount: flat map of relative path → content */
+  workspace?: Record<string, string>;
+  /** Extra npm dependencies to install: package → version */
+  services?: Record<string, string>;
+  /** Environment variables injected into the container */
+  env?: Record<string, string>;
+  /** Shell script to run after install, before agent launch */
+  startupScript?: string;
+  /** Template to use: name of a registered template, or a ContainerTemplate object. Default: 'gitclaw'. */
+  template?: string | ContainerTemplate;
+  /** Plugins to register before start */
+  plugins?: ClawContainerPlugin[];
+  /** Custom tabs to add on start */
+  tabs?: TabDefinition[];
+}
+
+/** Definition for a custom UI tab. */
+export interface TabDefinition {
+  /** Unique identifier for the tab */
+  id: string;
+  /** Display label in the tab bar */
+  label: string;
+  /** HTML content or a callback that receives the content container */
+  render: string | ((container: HTMLDivElement) => void);
+}
+
+/** Plugin lifecycle hooks. All are optional. */
+export interface ClawContainerPlugin {
+  /** Plugin name (for debugging) */
+  name: string;
+  /** Extra npm deps this plugin needs */
+  services?: Record<string, string>;
+  /** Extra workspace files to merge */
+  workspace?: Record<string, string>;
+  /** Extra env vars to inject */
+  env?: Record<string, string>;
+  /** Custom tabs to register */
+  tabs?: TabDefinition[];
+  /** Called after plugin is registered, before container boot */
+  onInit?(cc: ClawContainerSDK): void;
+  /** Called after container is ready */
+  onReady?(cc: ClawContainerSDK): void;
+  /** Called when container is stopped */
+  onDestroy?(cc: ClawContainerSDK): void;
+}
+
+/** Event map for ClawContainer typed events. */
+export type ClawContainerEvents = {
+  ready: [];
+  error: [error: Error];
+  status: [status: string];
+  'file.change': [path: string];
+  'process.exit': [code: number];
+  'server.ready': [port: number, url: string];
+  log: [entry: AuditEntry];
+};
+
+/**
+ * Public surface of the SDK passed to plugins.
+ * This is the same as ClawContainer but expressed as an interface
+ * so plugins don't depend on the concrete class.
+ */
+export interface ClawContainerSDK {
+  readonly container: WebContainer | null;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  restart(): Promise<void>;
+  exec(cmd: string): Promise<string>;
+  shell(): Promise<void>;
+  sendInput(data: string): Promise<void>;
+  fs: {
+    read(path: string): Promise<string>;
+    write(path: string, content: string): Promise<void>;
+    list(dir?: string): Promise<string[]>;
+    mkdir(path: string): Promise<void>;
+    remove(path: string): Promise<void>;
+  };
+  git: {
+    clone(url: string, token: string): Promise<void>;
+    push(message?: string): Promise<string>;
+  };
+  logs(filter?: { source?: AuditSource; level?: AuditLevel; event?: AuditEvent }): AuditEntry[];
+  use(plugin: ClawContainerPlugin): void;
+  addTab(def: TabDefinition): void;
+  removeTab(id: string): void;
+  on<K extends keyof ClawContainerEvents>(event: K, fn: (...args: ClawContainerEvents[K]) => void): void;
+  off<K extends keyof ClawContainerEvents>(event: K, fn: (...args: ClawContainerEvents[K]) => void): void;
+  once<K extends keyof ClawContainerEvents>(event: K, fn: (...args: ClawContainerEvents[K]) => void): void;
+}