@jhytabest/plashboard 0.1.0

package/src/fill-runner.ts

@@ -0,0 +1,122 @@
+import { spawn } from 'node:child_process';
+import type { FillResponse, FillRunContext, FillRunner, PlashboardConfig } from './types.js';
+
+function buildPromptPayload(context: FillRunContext): Record<string, unknown> {
+  return {
+    instructions: {
+      system: [
+        'Return JSON only.',
+        'Return exactly one object: {"values": {...}}.',
+        'Do not include markdown, explanations, or extra keys.'
+      ],
+      error_hint: context.errorHint || ''
+    },
+    template: {
+      id: context.template.id,
+      name: context.template.name,
+      context: context.template.context || {}
+    },
+    fields: context.template.fields.map((field) => ({
+      id: field.id,
+      type: field.type,
+      prompt: field.prompt,
+      required: field.required !== false,
+      constraints: field.constraints || {},
+      current_value: context.currentValues[field.id]
+    })),
+    expected_response_schema: {
+      values: {
+        '<field_id>': '<typed value>'
+      }
+    }
+  };
+}
+
+function mockValue(type: string, currentValue: unknown, fieldId: string): unknown {
+  if (type === 'number') return typeof currentValue === 'number' ? currentValue : 0;
+  if (type === 'boolean') return typeof currentValue === 'boolean' ? currentValue : false;
+  if (type === 'array') return Array.isArray(currentValue) ? currentValue : [];
+  const now = new Date().toISOString();
+  return `updated ${fieldId} at ${now}`;
+}
+
+class MockFillRunner implements FillRunner {
+  async run(context: FillRunContext): Promise<FillResponse> {
+    const values: Record<string, unknown> = {};
+    for (const field of context.template.fields) {
+      values[field.id] = mockValue(field.type, context.currentValues[field.id], field.id);
+    }
+    return { values };
+  }
+}
+
+function runCommand(command: string, promptPayload: Record<string, unknown>, timeoutSeconds: number): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, {
+      shell: true,
+      env: {
+        ...process.env,
+        PLASHBOARD_PROMPT_JSON: JSON.stringify(promptPayload)
+      }
+    });
+
+    const timer = setTimeout(() => {
+      child.kill('SIGKILL');
+      reject(new Error(`fill command timed out after ${timeoutSeconds}s`));
+    }, timeoutSeconds * 1000);
+
+    let stdout = '';
+    let stderr = '';
+
+    child.stdout.on('data', (chunk) => {
+      stdout += String(chunk);
+    });
+
+    child.stderr.on('data', (chunk) => {
+      stderr += String(chunk);
+    });
+
+    child.on('error', (error) => {
+      clearTimeout(timer);
+      reject(error);
+    });
+
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      if (code !== 0) {
+        reject(new Error(`fill command failed (code=${code}): ${stderr.trim() || 'no stderr'}`));
+        return;
+      }
+      resolve(stdout.trim());
+    });
+  });
+}
+
+class CommandFillRunner implements FillRunner {
+  constructor(private readonly config: PlashboardConfig) {}
+
+  async run(context: FillRunContext): Promise<FillResponse> {
+    if (!this.config.fill_command) {
+      throw new Error('fill_provider=command but fill_command is not configured');
+    }
+
+    const promptPayload = buildPromptPayload(context);
+    const output = await runCommand(this.config.fill_command, promptPayload, this.config.session_timeout_seconds);
+
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(output);
+    } catch {
+      throw new Error('fill command returned non-JSON output');
+    }
+
+    return parsed as FillResponse;
+  }
+}
+
+export function createFillRunner(config: PlashboardConfig): FillRunner {
+  if (config.fill_provider === 'command') {
+    return new CommandFillRunner(config);
+  }
+  return new MockFillRunner();
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+import { registerPlashboardPlugin } from './plugin.js';
+
+export default {
+  register(api: unknown) {
+    registerPlashboardPlugin(api as Parameters<typeof registerPlashboardPlugin>[0]);
+  }
+};

package/src/json-pointer.ts

@@ -0,0 +1,102 @@
+export function decodeToken(token: string): string {
+  return token.replaceAll('~1', '/').replaceAll('~0', '~');
+}
+
+export function parsePointer(pointer: string): string[] {
+  if (!pointer.startsWith('/')) {
+    throw new Error(`invalid pointer: ${pointer}`);
+  }
+  if (pointer === '/') return [''];
+  return pointer.slice(1).split('/').map(decodeToken);
+}
+
+function isArrayIndex(token: string): boolean {
+  return /^\d+$/.test(token);
+}
+
+export function readPointer(root: unknown, pointer: string): unknown {
+  const tokens = parsePointer(pointer);
+  let cursor: unknown = root;
+
+  for (const token of tokens) {
+    if (Array.isArray(cursor)) {
+      if (!isArrayIndex(token)) {
+        throw new Error(`pointer token must be numeric for array: ${pointer}`);
+      }
+      const index = Number(token);
+      if (!Number.isInteger(index) || index < 0 || index >= cursor.length) {
+        throw new Error(`array index out of range for pointer: ${pointer}`);
+      }
+      cursor = cursor[index];
+      continue;
+    }
+
+    if (cursor && typeof cursor === 'object') {
+      const record = cursor as Record<string, unknown>;
+      if (!(token in record)) {
+        throw new Error(`pointer path not found: ${pointer}`);
+      }
+      cursor = record[token];
+      continue;
+    }
+
+    throw new Error(`pointer path not found: ${pointer}`);
+  }
+
+  return cursor;
+}
+
+export function writePointer(root: unknown, pointer: string, value: unknown): void {
+  const tokens = parsePointer(pointer);
+  if (!tokens.length) throw new Error(`invalid pointer: ${pointer}`);
+
+  let cursor: unknown = root;
+  for (let index = 0; index < tokens.length - 1; index += 1) {
+    const token = tokens[index];
+
+    if (Array.isArray(cursor)) {
+      if (!isArrayIndex(token)) {
+        throw new Error(`pointer token must be numeric for array: ${pointer}`);
+      }
+      const arrayIndex = Number(token);
+      if (!Number.isInteger(arrayIndex) || arrayIndex < 0 || arrayIndex >= cursor.length) {
+        throw new Error(`array index out of range for pointer: ${pointer}`);
+      }
+      cursor = cursor[arrayIndex];
+      continue;
+    }
+
+    if (!cursor || typeof cursor !== 'object') {
+      throw new Error(`pointer path not found: ${pointer}`);
+    }
+
+    const record = cursor as Record<string, unknown>;
+    if (!(token in record)) {
+      throw new Error(`pointer path not found: ${pointer}`);
+    }
+    cursor = record[token];
+  }
+
+  const last = tokens[tokens.length - 1];
+  if (Array.isArray(cursor)) {
+    if (!isArrayIndex(last)) {
+      throw new Error(`pointer token must be numeric for array: ${pointer}`);
+    }
+    const index = Number(last);
+    if (!Number.isInteger(index) || index < 0 || index >= cursor.length) {
+      throw new Error(`array index out of range for pointer: ${pointer}`);
+    }
+    cursor[index] = value;
+    return;
+  }
+
+  if (!cursor || typeof cursor !== 'object') {
+    throw new Error(`pointer path not found: ${pointer}`);
+  }
+
+  const record = cursor as Record<string, unknown>;
+  if (!(last in record)) {
+    throw new Error(`pointer path not found: ${pointer}`);
+  }
+  record[last] = value;
+}

package/src/merge.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from 'vitest';
+import { mergeTemplateValues, validateFieldPointers } from './merge.js';
+import type { DashboardTemplate } from './types.js';
+
+function baseTemplate(): DashboardTemplate {
+  return {
+    id: 'ops',
+    name: 'Ops',
+    enabled: true,
+    schedule: {
+      mode: 'interval',
+      every_minutes: 10,
+      timezone: 'Europe/Berlin'
+    },
+    base_dashboard: {
+      title: 'Dashboard',
+      summary: 'Old',
+      ui: { timezone: 'Europe/Berlin' },
+      sections: [
+        {
+          id: 'sec',
+          label: 'Section',
+          cards: [
+            {
+              id: 'card',
+              title: 'Card',
+              description: 'desc'
+            }
+          ]
+        }
+      ],
+      alerts: []
+    },
+    fields: [
+      {
+        id: 'summary',
+        pointer: '/summary',
+        type: 'string',
+        prompt: 'Summary',
+        required: true,
+        constraints: { max_len: 80 }
+      }
+    ]
+  };
+}
+
+describe('mergeTemplateValues', () => {
+  it('merges valid values into base dashboard', () => {
+    const template = baseTemplate();
+    const merged = mergeTemplateValues(template, { summary: 'New summary' });
+    expect(merged.summary).toBe('New summary');
+    expect(template.base_dashboard.summary).toBe('Old');
+  });
+
+  it('rejects unknown field ids', () => {
+    const template = baseTemplate();
+    expect(() => mergeTemplateValues(template, { nope: 'x' })).toThrow(/unknown field id/i);
+  });
+
+  it('validates pointers exist in base dashboard', () => {
+    const template = baseTemplate();
+    template.fields[0].pointer = '/missing';
+    expect(() => validateFieldPointers(template)).toThrow(/pointer path not found/i);
+  });
+});

package/src/merge.ts

@@ -0,0 +1,108 @@
+import type { DashboardTemplate, FieldSpec } from './types.js';
+import { deepClone } from './utils.js';
+import { readPointer, writePointer } from './json-pointer.js';
+
+function assertFieldValue(field: FieldSpec, value: unknown): void {
+  const required = field.required !== false;
+  if (value === undefined || value === null) {
+    if (required) {
+      throw new Error(`missing required value for field ${field.id}`);
+    }
+    return;
+  }
+
+  if (field.type === 'string') {
+    if (typeof value !== 'string') {
+      throw new Error(`field ${field.id} expects string`);
+    }
+    if (field.constraints?.max_len && value.length > field.constraints.max_len) {
+      throw new Error(`field ${field.id} exceeds max_len=${field.constraints.max_len}`);
+    }
+  }
+
+  if (field.type === 'number') {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+      throw new Error(`field ${field.id} expects number`);
+    }
+    if (typeof field.constraints?.min === 'number' && value < field.constraints.min) {
+      throw new Error(`field ${field.id} below min=${field.constraints.min}`);
+    }
+    if (typeof field.constraints?.max === 'number' && value > field.constraints.max) {
+      throw new Error(`field ${field.id} above max=${field.constraints.max}`);
+    }
+  }
+
+  if (field.type === 'boolean') {
+    if (typeof value !== 'boolean') {
+      throw new Error(`field ${field.id} expects boolean`);
+    }
+  }
+
+  if (field.type === 'array') {
+    if (!Array.isArray(value)) {
+      throw new Error(`field ${field.id} expects array`);
+    }
+    if (typeof field.constraints?.min_items === 'number' && value.length < field.constraints.min_items) {
+      throw new Error(`field ${field.id} requires at least ${field.constraints.min_items} items`);
+    }
+    if (typeof field.constraints?.max_items === 'number' && value.length > field.constraints.max_items) {
+      throw new Error(`field ${field.id} allows at most ${field.constraints.max_items} items`);
+    }
+  }
+
+  if (field.constraints?.enum && !field.constraints.enum.includes(value as never)) {
+    throw new Error(`field ${field.id} value not in enum`);
+  }
+}
+
+export function validateFieldPointers(template: DashboardTemplate): void {
+  const seenPointers = new Set<string>();
+  const seenIds = new Set<string>();
+
+  for (const field of template.fields) {
+    if (seenIds.has(field.id)) {
+      throw new Error(`duplicate field id: ${field.id}`);
+    }
+    seenIds.add(field.id);
+
+    if (seenPointers.has(field.pointer)) {
+      throw new Error(`duplicate field pointer: ${field.pointer}`);
+    }
+    seenPointers.add(field.pointer);
+
+    readPointer(template.base_dashboard, field.pointer);
+  }
+}
+
+export function mergeTemplateValues(
+  template: DashboardTemplate,
+  values: Record<string, unknown>
+): Record<string, unknown> {
+  const next = deepClone(template.base_dashboard);
+  const knownIds = new Set(template.fields.map((field) => field.id));
+
+  for (const fieldId of Object.keys(values)) {
+    if (!knownIds.has(fieldId)) {
+      throw new Error(`unknown field id in fill response: ${fieldId}`);
+    }
+  }
+
+  for (const field of template.fields) {
+    const value = values[field.id];
+    assertFieldValue(field, value);
+
+    if (value !== undefined && value !== null) {
+      writePointer(next, field.pointer, value);
+    }
+  }
+
+  return next;
+}
+
+export function collectCurrentValues(template: DashboardTemplate): Record<string, unknown> {
+  const values: Record<string, unknown> = {};
+  for (const field of template.fields) {
+    values[field.id] = readPointer(template.base_dashboard, field.pointer);
+  }
+  return values;
+}

package/src/plugin.ts

@@ -0,0 +1,272 @@
+import type { DisplayProfile, ToolResponse } from './types.js';
+import { resolveConfig } from './config.js';
+import { PlashboardRuntime } from './runtime.js';
+
+type UnknownApi = {
+  registerTool?: (definition: unknown) => void;
+  registerCommand?: (definition: unknown) => void;
+  registerService?: (definition: unknown) => void;
+  logger?: {
+    info?: (...args: unknown[]) => void;
+    warn?: (...args: unknown[]) => void;
+    error?: (...args: unknown[]) => void;
+  };
+  config?: unknown;
+  pluginConfig?: unknown;
+};
+
+function toToolResult<T>(payload: ToolResponse<T>) {
+  return {
+    content: [
+      {
+        type: 'text',
+        text: JSON.stringify(payload)
+      }
+    ]
+  };
+}
+
+function toCommandResult<T>(payload: ToolResponse<T>) {
+  return {
+    text: JSON.stringify(payload)
+  };
+}
+
+function asObject(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function asString(value: unknown): string {
+  return typeof value === 'string' ? value : '';
+}
+
+export function registerPlashboardPlugin(api: UnknownApi): void {
+  const config = resolveConfig(api);
+  const runtime = new PlashboardRuntime(config, {
+    info: (...args) => api.logger?.info?.(...args),
+    warn: (...args) => api.logger?.warn?.(...args),
+    error: (...args) => api.logger?.error?.(...args)
+  });
+
+  api.registerService?.({
+    id: 'plashboard-scheduler',
+    async start() {
+      await runtime.start();
+    },
+    async stop() {
+      await runtime.stop();
+    }
+  });
+
+  api.registerTool?.({
+    name: 'plashboard_init',
+    description: 'Initialize plashboard state directories and optional default template.',
+    optional: true,
+    execute: async () => toToolResult(await runtime.init())
+  });
+
+  api.registerTool?.({
+    name: 'plashboard_template_create',
+    description: 'Create a new dashboard template.',
+    optional: true,
+    parameters: {
+      type: 'object',
+      required: ['template'],
+      properties: {
+        template: { type: 'object' }
+      },
+      additionalProperties: false
+    },
+    execute: async (_toolCallId: unknown, params: { template?: unknown } = {}) =>
+      toToolResult(await runtime.templateCreate(params.template))
+  });
+
+  api.registerTool?.({
+    name: 'plashboard_template_update',
+    description: 'Update an existing dashboard template.',
+    optional: true,
+    parameters: {
+      type: 'object',
+      required: ['template_id', 'template'],
+      properties: {
+        template_id: { type: 'string' },
+        template: { type: 'object' }
+      },
+      additionalProperties: false
+    },
+    execute: async (_toolCallId: unknown, params: { template_id?: string; template?: unknown } = {}) =>
+      toToolResult(await runtime.templateUpdate(params.template_id || '', params.template))
+  });
+
+  api.registerTool?.({
+    name: 'plashboard_template_list',
+    description: 'List available dashboard templates with schedule and run state.',
+    optional: true,
+    execute: async () => toToolResult(await runtime.templateList())
+  });
+
+  api.registerTool?.({
+    name: 'plashboard_template_activate',
+    description: 'Set active dashboard template.',
+    optional: true,
+    parameters: {
+      type: 'object',
+      required: ['template_id'],
+      properties: {
+        template_id: { type: 'string' }
+      },
+      additionalProperties: false
+    },
+    execute: async (_toolCallId: unknown, params: { template_id?: string } = {}) =>
+      toToolResult(await runtime.templateActivate(params.template_id || ''))
+  });
+
+  api.registerTool?.({
+    name: 'plashboard_template_delete',
+    description: 'Delete a dashboard template by id.',
+    optional: true,
+    parameters: {
+      type: 'object',
+      required: ['template_id'],
+      properties: {
+        template_id: { type: 'string' }
+      },
+      additionalProperties: false
+    },
+    execute: async (_toolCallId: unknown, params: { template_id?: string } = {}) =>
+      toToolResult(await runtime.templateDelete(params.template_id || ''))
+  });
+
+  api.registerTool?.({
+    name: 'plashboard_template_copy',
+    description: 'Copy a dashboard template into a new template id.',
+    optional: true,
+    parameters: {
+      type: 'object',
+      required: ['source_template_id', 'new_template_id'],
+      properties: {
+        source_template_id: { type: 'string' },
+        new_template_id: { type: 'string' },
+        new_name: { type: 'string' },
+        activate: { type: 'boolean' }
+      },
+      additionalProperties: false
+    },
+    execute: async (
+      _toolCallId: unknown,
+      params: {
+        source_template_id?: string;
+        new_template_id?: string;
+        new_name?: string;
+        activate?: boolean;
+      } = {}
+    ) =>
+      toToolResult(
+        await runtime.templateCopy(
+          params.source_template_id || '',
+          params.new_template_id || '',
+          params.new_name,
+          Boolean(params.activate)
+        )
+      )
+  });
+
+  api.registerTool?.({
+    name: 'plashboard_template_validate',
+    description: 'Validate a dashboard template payload without saving.',
+    optional: true,
+    parameters: {
+      type: 'object',
+      required: ['template'],
+      properties: {
+        template: { type: 'object' }
+      },
+      additionalProperties: false
+    },
+    execute: async (_toolCallId: unknown, params: { template?: unknown } = {}) =>
+      toToolResult(await runtime.templateValidate(params.template))
+  });
+
+  api.registerTool?.({
+    name: 'plashboard_run_now',
+    description: 'Run fill pipeline for a template immediately.',
+    optional: true,
+    parameters: {
+      type: 'object',
+      required: ['template_id'],
+      properties: {
+        template_id: { type: 'string' }
+      },
+      additionalProperties: false
+    },
+    execute: async (_toolCallId: unknown, params: { template_id?: string } = {}) =>
+      toToolResult(await runtime.runNow(params.template_id || ''))
+  });
+
+  api.registerTool?.({
+    name: 'plashboard_status',
+    description: 'Read current plashboard runtime status.',
+    optional: true,
+    execute: async () => toToolResult(await runtime.status())
+  });
+
+  api.registerTool?.({
+    name: 'plashboard_display_profile_set',
+    description: 'Update display profile for layout budget enforcement.',
+    optional: true,
+    parameters: {
+      type: 'object',
+      properties: {
+        width_px: { type: 'number' },
+        height_px: { type: 'number' },
+        safe_top_px: { type: 'number' },
+        safe_bottom_px: { type: 'number' },
+        safe_side_px: { type: 'number' },
+        layout_safety_margin_px: { type: 'number' }
+      },
+      additionalProperties: false
+    },
+    execute: async (_toolCallId: unknown, params: Partial<DisplayProfile> = {}) =>
+      toToolResult(await runtime.displayProfileSet(params))
+  });
+
+  api.registerCommand?.({
+    name: 'plashboard',
+    description: 'Plashboard admin command wrapper for common runtime operations.',
+    acceptsArgs: true,
+    handler: async (ctx: { args?: string }) => {
+      const args = asString(ctx.args).split(/\s+/).filter(Boolean);
+      const [cmd, ...rest] = args;
+
+      if (cmd === 'init') return toCommandResult(await runtime.init());
+      if (cmd === 'status') return toCommandResult(await runtime.status());
+      if (cmd === 'list') return toCommandResult(await runtime.templateList());
+      if (cmd === 'activate') return toCommandResult(await runtime.templateActivate(rest[0] || ''));
+      if (cmd === 'delete') return toCommandResult(await runtime.templateDelete(rest[0] || ''));
+      if (cmd === 'copy') {
+        return toCommandResult(
+          await runtime.templateCopy(rest[0] || '', rest[1] || '', rest[2] || undefined, rest[3] === 'activate')
+        );
+      }
+      if (cmd === 'run') return toCommandResult(await runtime.runNow(rest[0] || ''));
+      if (cmd === 'set-display') {
+        const input = asObject({
+          width_px: rest[0] ? Number(rest[0]) : undefined,
+          height_px: rest[1] ? Number(rest[1]) : undefined,
+          safe_top_px: rest[2] ? Number(rest[2]) : undefined,
+          safe_bottom_px: rest[3] ? Number(rest[3]) : undefined
+        });
+        return toCommandResult(await runtime.displayProfileSet(input as Partial<DisplayProfile>));
+      }
+
+      return toCommandResult({
+        ok: false,
+        errors: [
+          'unknown command. supported: init, status, list, activate <id>, delete <id>, copy <src> <new-id> [new-name] [activate], run <id>, set-display <width> <height> <top> <bottom>'
+        ]
+      });
+    }
+  });
+}