@jhytabest/plashboard 0.1.10 → 1.0.0

package/README.md

@@ -23,6 +23,7 @@ openclaw plugins update plashboard
 
 No manual config is required for first use. Defaults are safe:
 - `fill_provider=openclaw`
+- `allow_command_fill=false`
 - `openclaw_fill_agent_id=main`
 - automatic init on service start
 - automatic starter template seed when template store is empty
@@ -33,6 +34,9 @@ In chat, run:
 /plashboard onboard <what this dashboard should focus on>
 ```
 
+For end users (Telegram/other channels), no slash command is required:
+natural-language requests such as "I want a dashboard for X" are handled by the bundled `plashboard-admin` skill via tool calls.
+
 ## Optional Config
 
 Add to `openclaw.json`:
@@ -52,6 +56,7 @@ Add to `openclaw.json`:
           "session_timeout_seconds": 90,
           "auto_seed_template": true,
           "fill_provider": "openclaw",
+          "allow_command_fill": false,
           "openclaw_fill_agent_id": "main",
           "display_profile": {
             "width_px": 1920,
@@ -69,7 +74,20 @@ Add to `openclaw.json`:
 ```
 
 `fill_provider: "openclaw"` is the default real mode and calls `openclaw agent` directly.
-Use `fill_provider: "command"` only if you need a custom external runner.
+`fill_provider: "command"` requires explicit opt-in with `allow_command_fill: true`.
+Use command mode only if you need a custom external runner.
+
+For production stability, use a dedicated fill agent instead of `main`:
+
+```bash
+openclaw agents add plashboard-fill --non-interactive --workspace /var/lib/openclaw/.openclaw/workspace-plashboard-fill
+```
+
+Then run:
+
+```text
+/plashboard setup openclaw plashboard-fill
+```
 
 ## Runtime Command
 
@@ -78,6 +96,7 @@ Use `fill_provider: "command"` only if you need a custom external runner.
 /plashboard setup [openclaw [agent_id]|mock|command <fill_command>]
 /plashboard quickstart <description>
 /plashboard doctor [local_url] [https_port] [repo_dir]
+/plashboard fix-permissions [dashboard_output_path]
 /plashboard web-guide [local_url] [repo_dir]
 /plashboard expose-guide [local_url] [https_port]
 /plashboard expose-check [local_url] [https_port]
@@ -97,12 +116,21 @@ Recommended first run:
 /plashboard onboard "Focus on service health, priorities, blockers, and next actions."
 ```
 
+For command mode, explicit opt-in is required:
+
+```text
+/plashboard setup command <fill_command>
+```
+
+This command writes `allow_command_fill=true` with `fill_provider=command`.
+
 If `onboard` returns web/exposure warnings:
 
 ```text
 /plashboard web-guide
 /plashboard expose-guide
 /plashboard doctor
+/plashboard fix-permissions
 ```
 
 Tailscale helper flow:
@@ -116,3 +144,5 @@ Tailscale helper flow:
 
 - The plugin includes an admin skill (`plashboard-admin`) for tool-guided management.
 - Trusted publishing (OIDC) is enabled in CI/CD for npm releases.
+- If you see `plugins.allow is empty`, add explicit trust list in OpenClaw config:
+  - `"plugins": { "allow": ["plashboard"] }`

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "plashboard",
   "name": "Plashboard",
-  "version": "0.1.10",
+  "version": "1.0.0",
   "description": "Template-driven dashboard runtime with scheduled OpenClaw fills and safe publish.",
   "entry": "./src/index.ts",
   "skills": ["./skills/plashboard-admin"],
@@ -17,6 +17,7 @@
       "session_timeout_seconds": { "type": "integer", "minimum": 10, "maximum": 600, "default": 90 },
       "auto_seed_template": { "type": "boolean", "default": true },
       "fill_provider": { "type": "string", "enum": ["command", "mock", "openclaw"], "default": "openclaw" },
+      "allow_command_fill": { "type": "boolean", "default": false },
       "fill_command": { "type": "string" },
       "openclaw_fill_agent_id": { "type": "string", "default": "main" },
       "python_bin": { "type": "string", "default": "python3" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jhytabest/plashboard",
-  "version": "0.1.10",
+  "version": "1.0.0",
   "private": false,
   "description": "Plashboard OpenClaw plugin runtime",
   "license": "MIT",
@@ -17,7 +17,7 @@
   "files": [
     "openclaw.plugin.json",
     "schema",
-    "scripts",
+    "scripts/dashboard_write.py",
     "skills",
     "src",
     "tsconfig.json",
@@ -27,6 +27,7 @@
     "access": "public"
   },
   "scripts": {
+    "security:scan": "node ./dev-security-scan.mjs",
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit"

package/skills/plashboard-admin/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: plashboard-admin
-description: Manage plashboard templates, activation, copy/delete, run-now triggers, and display profile using plashboard plugin tools.
+description: Manage plashboard templates and autonomously convert natural-language dashboard requests into plashboard tool actions.
 command-dispatch: tool
 ---
 
@@ -9,6 +9,7 @@ command-dispatch: tool
 Use this skill for plashboard runtime administration.
 
 ## Use Cases
+- Convert user requests like "I want dashboard X" into created/activated dashboards automatically.
 - Create, update, copy, delete, and validate dashboard templates.
 - Activate a template as the live dashboard source.
 - Trigger immediate runs.
@@ -23,6 +24,7 @@ Always use plugin tools:
 - `plashboard_exposure_check`
 - `plashboard_web_guide`
 - `plashboard_doctor`
+- `plashboard_permissions_fix`
 - `plashboard_init`
 - `plashboard_quickstart`
 - `plashboard_template_create`
@@ -41,12 +43,24 @@ Always use plugin tools:
 - Never edit template/state/run JSON files directly.
 - Never perform Docker, Tailscale, or systemd operations.
 - Never ask the model to generate full dashboard structure when filling values.
+- Do not tell end users to run slash commands when tool calls can do the action directly.
+
+## Intent Automation
+- If the user asks for a new dashboard in natural language, call `plashboard_onboard` with:
+  - `description`: user request rewritten as a concrete dashboard objective
+  - `force_quickstart`: `true`
+  - `activate`: `true`
+  - `run_now`: `true`
+- If onboarding returns readiness issues, call `plashboard_web_guide` and `plashboard_exposure_guide`, then present exact operator commands.
+- If the user asks to modify an existing dashboard, call `plashboard_template_list` first, then update/copy/activate/run via tools.
+- Prefer tool execution over conversational planning; only ask clarifying questions if the request is ambiguous.
 
 ## Command Shortcuts
 - `/plashboard onboard <description> [local_url] [https_port] [repo_dir]`
 - `/plashboard quickstart <description>`
 - `/plashboard setup [openclaw [agent_id]|mock|command <fill_command>]`
 - `/plashboard doctor [local_url] [https_port] [repo_dir]`
+- `/plashboard fix-permissions [dashboard_output_path]`
 - `/plashboard web-guide [local_url] [repo_dir]`
 - `/plashboard expose-guide [local_url] [https_port]`
 - `/plashboard expose-check [local_url] [https_port]`

package/src/command-runner.ts

@@ -0,0 +1,120 @@
+type CommandRunnerOptions = {
+  timeoutMs: number;
+  cwd?: string;
+  input?: string;
+  env?: Record<string, string>;
+  windowsVerbatimArguments?: boolean;
+  noOutputTimeoutMs?: number;
+};
+
+export type CommandRunResult = {
+  stdout: string;
+  stderr: string;
+  code: number | null;
+  signal?: NodeJS.Signals | null;
+  killed?: boolean;
+  termination?: 'exit' | 'timeout' | 'signal' | string;
+};
+
+export type CommandRunner = (
+  argv: string[],
+  optionsOrTimeout: number | CommandRunnerOptions
+) => Promise<CommandRunResult>;
+
+export type RuntimeCommandWithTimeout = (
+  argv: string[],
+  optionsOrTimeout: number | CommandRunnerOptions
+) => Promise<{
+  stdout: string;
+  stderr: string;
+  code: number | null;
+  signal?: NodeJS.Signals | null;
+  killed?: boolean;
+  termination?: string;
+}>;
+
+export type CommandExecResult = {
+  ok: boolean;
+  stdout: string;
+  stderr: string;
+  code: number | null;
+  signal?: NodeJS.Signals | null;
+  killed?: boolean;
+  termination?: string;
+  error?: string;
+};
+
+function asErrorMessage(error: unknown): string {
+  if (error instanceof Error && error.message) return error.message;
+  if (typeof error === 'string' && error.trim()) return error;
+  return 'unknown error';
+}
+
+export function createRuntimeCommandRunner(runtimeCommand?: RuntimeCommandWithTimeout): CommandRunner | null {
+  if (!runtimeCommand) return null;
+  return async (argv: string[], optionsOrTimeout: number | CommandRunnerOptions): Promise<CommandRunResult> => {
+    const result = await runtimeCommand(argv, optionsOrTimeout);
+    return {
+      stdout: result.stdout,
+      stderr: result.stderr,
+      code: result.code,
+      signal: result.signal,
+      killed: result.killed,
+      termination: result.termination
+    };
+  };
+}
+
+export async function runCommand(
+  commandRunner: CommandRunner | null | undefined,
+  argv: string[],
+  optionsOrTimeout: number | CommandRunnerOptions,
+  label: string
+): Promise<CommandExecResult> {
+  if (!commandRunner) {
+    return {
+      ok: false,
+      stdout: '',
+      stderr: '',
+      code: null,
+      error: `${label} is unavailable: OpenClaw runtime command runner is not available`
+    };
+  }
+
+  try {
+    const result = await commandRunner(argv, optionsOrTimeout);
+    return {
+      ok: result.code === 0,
+      stdout: result.stdout.trim(),
+      stderr: result.stderr.trim(),
+      code: result.code,
+      signal: result.signal,
+      killed: result.killed,
+      termination: result.termination
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      stdout: '',
+      stderr: '',
+      code: null,
+      error: `${label} failed: ${asErrorMessage(error)}`
+    };
+  }
+}
+
+export async function runAndReadStdout(
+  commandRunner: CommandRunner | null | undefined,
+  argv: string[],
+  optionsOrTimeout: number | CommandRunnerOptions,
+  label: string
+): Promise<string> {
+  const result = await runCommand(commandRunner, argv, optionsOrTimeout, label);
+  if (!result.ok) {
+    const reason = result.error || result.stderr || result.stdout || result.termination || `exit=${String(result.code)}`;
+    throw new Error(`${label} failed: ${reason}`);
+  }
+  return result.stdout.trim();
+}
+
+export type { CommandRunnerOptions };

package/src/config.ts

@@ -77,6 +77,7 @@ export function resolveConfig(api: unknown): PlashboardConfig {
     session_timeout_seconds: Math.max(10, Math.floor(asNumber(raw.session_timeout_seconds, 90))),
     auto_seed_template: asBoolean(raw.auto_seed_template, true),
     fill_provider: fillProvider,
+    allow_command_fill: asBoolean(raw.allow_command_fill, false),
     fill_command: typeof raw.fill_command === 'string' ? raw.fill_command : undefined,
     openclaw_fill_agent_id: asString(raw.openclaw_fill_agent_id, 'main'),
     python_bin: asString(raw.python_bin, 'python3'),

package/src/fill-runner.test.ts

@@ -39,6 +39,7 @@ function config(overrides: Partial<PlashboardConfig>): PlashboardConfig {
     session_timeout_seconds: 30,
     auto_seed_template: false,
     fill_provider: 'mock',
+    allow_command_fill: false,
     fill_command: undefined,
     openclaw_fill_agent_id: 'main',
     python_bin: 'python3',
@@ -105,7 +106,7 @@ describe('createFillRunner', () => {
     }));
 
     const runner = createFillRunner(
-      config({ fill_provider: 'command', fill_command: 'echo "$PLASHBOARD_PROMPT_JSON"' }),
+      config({ fill_provider: 'command', allow_command_fill: true, fill_command: 'echo "$PLASHBOARD_PROMPT_JSON"' }),
       { commandRunner }
     );
     const response = await runner.run(context());
@@ -118,4 +119,20 @@ describe('createFillRunner', () => {
     const options = firstCall[1] as { env?: Record<string, string> };
     expect(options.env?.PLASHBOARD_PROMPT_JSON).toContain('"template"');
   });
+
+  it('rejects command fill when allow_command_fill is false', async () => {
+    const commandRunner = vi.fn(async () => ({
+      stdout: '{"values":{"summary":"from command"}}',
+      stderr: '',
+      code: 0
+    }));
+
+    const runner = createFillRunner(
+      config({ fill_provider: 'command', allow_command_fill: false, fill_command: 'echo hello' }),
+      { commandRunner }
+    );
+
+    await expect(runner.run(context())).rejects.toThrow(/allow_command_fill=true/);
+    expect(commandRunner).not.toHaveBeenCalled();
+  });
 });

package/src/fill-runner.ts

@@ -1,28 +1,8 @@
-import { spawn } from 'node:child_process';
+import { runAndReadStdout, type CommandRunner } from './command-runner.js';
 import type { FillResponse, FillRunContext, FillRunner, PlashboardConfig } from './types.js';
 
-type CommandOptions = {
-  timeoutMs: number;
-  env?: NodeJS.ProcessEnv;
-  input?: string;
-};
-
-export type CommandRunResult = {
-  stdout: string;
-  stderr: string;
-  code: number | null;
-  signal?: NodeJS.Signals | null;
-  killed?: boolean;
-  termination?: 'exit' | 'timeout' | 'signal' | string;
-};
-
-export type CommandRunner = (
-  argv: string[],
-  optionsOrTimeout: number | CommandOptions
-) => Promise<CommandRunResult>;
-
 export interface FillRunnerDeps {
-  commandRunner?: CommandRunner;
+  commandRunner?: CommandRunner | null;
 }
 
 function buildPromptPayload(context: FillRunContext): Record<string, unknown> {
@@ -74,70 +54,6 @@ function mockValue(type: string, currentValue: unknown, fieldId: string): unknow
   return `updated ${fieldId} at ${now}`;
 }
 
-function normalizeCommandOptions(optionsOrTimeout: number | CommandOptions): CommandOptions {
-  if (typeof optionsOrTimeout === 'number') {
-    return { timeoutMs: optionsOrTimeout };
-  }
-  return { timeoutMs: optionsOrTimeout.timeoutMs, env: optionsOrTimeout.env, input: optionsOrTimeout.input };
-}
-
-function defaultCommandRunner(argv: string[], optionsOrTimeout: number | CommandOptions): Promise<CommandRunResult> {
-  const options = normalizeCommandOptions(optionsOrTimeout);
-  return new Promise((resolve, reject) => {
-    if (!Array.isArray(argv) || argv.length === 0 || !argv[0]) {
-      reject(new Error('command argv must include a binary name'));
-      return;
-    }
-
-    const child = spawn(argv[0], argv.slice(1), {
-      env: {
-        ...process.env,
-        ...(options.env || {})
-      },
-      stdio: 'pipe'
-    });
-
-    const timeoutMs = Math.max(1000, Math.floor(options.timeoutMs));
-    let terminatedByTimeout = false;
-    const timer = setTimeout(() => {
-      terminatedByTimeout = true;
-      child.kill('SIGKILL');
-    }, timeoutMs);
-
-    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, signal) => {
-      clearTimeout(timer);
-      resolve({
-        stdout: stdout.trim(),
-        stderr: stderr.trim(),
-        code,
-        signal,
-        killed: terminatedByTimeout || code === null,
-        termination: terminatedByTimeout ? 'timeout' : signal ? 'signal' : 'exit'
-      });
-    });
-
-    if (typeof options.input === 'string') {
-      child.stdin.write(options.input);
-    }
-    child.stdin.end();
-  });
-}
-
 function tryParseJson(input: string): unknown | undefined {
   try {
     return JSON.parse(input);
@@ -226,20 +142,6 @@ function parseFillResponse(output: string, source: string): FillResponse {
   return extracted;
 }
 
-async function runAndReadStdout(
-  commandRunner: CommandRunner,
-  argv: string[],
-  optionsOrTimeout: number | CommandOptions,
-  label: string
-): Promise<string> {
-  const result = await commandRunner(argv, optionsOrTimeout);
-  if (result.code !== 0) {
-    const reason = result.stderr || result.stdout || result.termination || `exit=${String(result.code)}`;
-    throw new Error(`${label} failed: ${reason}`);
-  }
-  return result.stdout.trim();
-}
-
 class MockFillRunner implements FillRunner {
   async run(context: FillRunContext): Promise<FillResponse> {
     const values: Record<string, unknown> = {};
@@ -253,10 +155,13 @@ class MockFillRunner implements FillRunner {
 class CommandFillRunner implements FillRunner {
   constructor(
     private readonly config: PlashboardConfig,
-    private readonly commandRunner: CommandRunner
+    private readonly commandRunner: CommandRunner | null
   ) {}
 
   async run(context: FillRunContext): Promise<FillResponse> {
+    if (!this.config.allow_command_fill) {
+      throw new Error('fill_provider=command is disabled; set allow_command_fill=true to enable it');
+    }
     if (!this.config.fill_command) {
       throw new Error('fill_provider=command but fill_command is not configured');
     }
@@ -280,7 +185,7 @@ class CommandFillRunner implements FillRunner {
 class OpenClawFillRunner implements FillRunner {
   constructor(
     private readonly config: PlashboardConfig,
-    private readonly commandRunner: CommandRunner
+    private readonly commandRunner: CommandRunner | null
   ) {}
 
   async run(context: FillRunContext): Promise<FillResponse> {
@@ -302,7 +207,7 @@ class OpenClawFillRunner implements FillRunner {
 }
 
 export function createFillRunner(config: PlashboardConfig, deps: FillRunnerDeps = {}): FillRunner {
-  const commandRunner = deps.commandRunner || defaultCommandRunner;
+  const commandRunner = deps.commandRunner ?? null;
   if (config.fill_provider === 'command') {
     return new CommandFillRunner(config, commandRunner);
   }

package/src/plugin.test.ts

@@ -0,0 +1,186 @@
+import { chmod, mkdtemp, rm, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { describe, expect, it } from 'vitest';
+import { registerPlashboardPlugin } from './plugin.js';
+
+type ToolDef = {
+  name: string;
+  execute?: (toolCallId: unknown, params?: Record<string, unknown>) => Promise<{
+    content: Array<{ type: string; text: string }>;
+  }>;
+};
+
+function parseToolJson(result: { content: Array<{ type: string; text: string }> }) {
+  const text = result.content[0]?.text || '{}';
+  return JSON.parse(text) as Record<string, unknown>;
+}
+
+describe('registerPlashboardPlugin', () => {
+  it('doctor reports readiness flags when runtime command runner is unavailable', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'plashboard-plugin-test-'));
+    try {
+      const tools = new Map<string, ToolDef>();
+
+      registerPlashboardPlugin({
+        pluginConfig: {
+          config: {
+            data_dir: root,
+            dashboard_output_path: join(root, 'dashboard.json'),
+            fill_provider: 'openclaw',
+            allow_command_fill: false
+          }
+        },
+        registerTool: (definition: unknown) => {
+          const tool = definition as ToolDef;
+          tools.set(tool.name, tool);
+        },
+        registerCommand: () => {},
+        registerService: () => {},
+        runtime: {
+          config: {
+            loadConfig: () => ({}),
+            writeConfigFile: async () => {}
+          }
+        }
+      });
+
+      const doctor = tools.get('plashboard_doctor');
+      expect(doctor?.execute).toBeTypeOf('function');
+
+      const result = await doctor!.execute!('tool-1', {
+        local_url: 'http://127.0.0.1:9'
+      });
+      const payload = parseToolJson(result);
+      const data = (payload.data || {}) as Record<string, unknown>;
+
+      expect(payload.ok).toBe(false);
+      expect(data.fill_provider_ready).toBe(false);
+      expect(data.writer_runner_ready).toBe(false);
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  it('setup rejects command provider unless allow_command_fill is true', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'plashboard-plugin-test-'));
+    try {
+      const tools = new Map<string, ToolDef>();
+      let writtenConfig: unknown;
+
+      registerPlashboardPlugin({
+        pluginConfig: {
+          config: {
+            data_dir: root,
+            dashboard_output_path: join(root, 'dashboard.json'),
+            fill_provider: 'openclaw',
+            allow_command_fill: false
+          }
+        },
+        registerTool: (definition: unknown) => {
+          const tool = definition as ToolDef;
+          tools.set(tool.name, tool);
+        },
+        registerCommand: () => {},
+        registerService: () => {},
+        runtime: {
+          config: {
+            loadConfig: () => ({}),
+            writeConfigFile: async (nextConfig: unknown) => {
+              writtenConfig = nextConfig;
+            }
+          },
+          system: {
+            runCommandWithTimeout: async (argv: string[]) => {
+              if (argv[0] === 'python3' && argv[1] === '--version') {
+                return {
+                  stdout: 'Python 3.12.0',
+                  stderr: '',
+                  code: 0,
+                  termination: 'exit'
+                };
+              }
+              return {
+                stdout: '',
+                stderr: `unsupported command: ${argv.join(' ')}`,
+                code: 1,
+                termination: 'exit'
+              };
+            }
+          }
+        }
+      });
+
+      const setup = tools.get('plashboard_setup');
+      expect(setup?.execute).toBeTypeOf('function');
+
+      const rejected = parseToolJson(await setup!.execute!('tool-2', {
+        fill_provider: 'command',
+        fill_command: 'echo hello'
+      }));
+
+      expect(rejected.ok).toBe(false);
+      expect((rejected.errors as string[]).join(' ')).toMatch(/allow_command_fill=true/i);
+      expect(writtenConfig).toBeUndefined();
+
+      const accepted = parseToolJson(await setup!.execute!('tool-3', {
+        fill_provider: 'command',
+        allow_command_fill: true,
+        fill_command: 'echo hello'
+      }));
+
+      expect(accepted.ok).toBe(true);
+      expect((accepted.data as Record<string, unknown>).allow_command_fill).toBe(true);
+      expect(writtenConfig).toBeTruthy();
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  it('permissions fix normalizes directory and dashboard file modes', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'plashboard-plugin-test-'));
+    const dashboardPath = join(root, 'dashboard.json');
+    try {
+      const tools = new Map<string, ToolDef>();
+      await writeFile(dashboardPath, '{"ok":true}\n', 'utf8');
+      await chmod(root, 0o700);
+      await chmod(dashboardPath, 0o600);
+
+      registerPlashboardPlugin({
+        pluginConfig: {
+          config: {
+            data_dir: root,
+            dashboard_output_path: dashboardPath,
+            fill_provider: 'openclaw',
+            allow_command_fill: false
+          }
+        },
+        registerTool: (definition: unknown) => {
+          const tool = definition as ToolDef;
+          tools.set(tool.name, tool);
+        },
+        registerCommand: () => {},
+        registerService: () => {},
+        runtime: {
+          config: {
+            loadConfig: () => ({}),
+            writeConfigFile: async () => {}
+          }
+        }
+      });
+
+      const fix = tools.get('plashboard_permissions_fix');
+      expect(fix?.execute).toBeTypeOf('function');
+
+      const result = parseToolJson(await fix!.execute!('tool-4', {}));
+      expect(result.ok).toBe(true);
+
+      const dirMode = (await stat(root)).mode & 0o777;
+      const fileMode = (await stat(dashboardPath)).mode & 0o777;
+      expect(dirMode).toBe(0o755);
+      expect(fileMode).toBe(0o644);
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+});