@restormel/doctor 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Allotment Technology Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,55 @@
+# @restormel/doctor
+
+Restormel Doctor is an **open-source** CLI that checks your local setup and surfaces actionable “what to fix next” issues. It is designed to be the **entrypoint** into the Restormel Platform.
+
+## Install
+
+```bash
+npx @restormel/doctor
+```
+
+Or install globally / in a repo:
+
+```bash
+pnpm add -D @restormel/doctor
+```
+
+## Usage
+
+```bash
+restormel-doctor
+```
+
+### Output formats
+
+- **Text (default)**:
+
+```bash
+restormel-doctor
+```
+
+- **JSON (for CI/artifacts)**:
+
+```bash
+restormel-doctor --format json
+restormel-doctor --format json --out doctor.json
+```
+
+### Exit codes
+
+- `0`: no blocking issues found
+- `1`: blocking issues found
+- `2`: usage/config error (unexpected failure)
+
+## What it checks (v1)
+
+- Framework detection (Next.js / React / SvelteKit / Astro)
+- `restormel.config.json` presence + parseability
+- Suggested Restormel packages installed
+- Local key store presence (keys are never printed raw)
+
+## Relationship to Restormel Keys
+
+- `@restormel/doctor` is standalone and open source.
+- Restormel Keys (dashboard) will expose a **Pro** Healthcheck UI that aggregates Doctor + Validate signals across integrations, models, routes, and policies.
+

package/dist/config.d.ts

@@ -0,0 +1,6 @@
+export declare const CONFIG_FILENAME = "restormel.config.json";
+export interface RestormelConfig {
+    framework?: string;
+    providers?: string[];
+}
+export declare function readConfig(cwd: string): Promise<RestormelConfig | null>;

package/dist/config.js

@@ -0,0 +1,24 @@
+/**
+ * Project config for Restormel. No secrets — only framework and provider list.
+ */
+import { readFile } from "fs/promises";
+import { existsSync } from "fs";
+import { join } from "path";
+export const CONFIG_FILENAME = "restormel.config.json";
+const DEFAULT_CONFIG = {
+    framework: "none",
+    providers: [],
+};
+export async function readConfig(cwd) {
+    const path = join(cwd, CONFIG_FILENAME);
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = await readFile(path, "utf-8");
+        const data = JSON.parse(raw);
+        return { ...DEFAULT_CONFIG, ...data };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/detect.d.ts

@@ -0,0 +1,8 @@
+export type FrameworkId = "next" | "react" | "sveltekit" | "astro" | "none";
+export interface DetectedFramework {
+    id: FrameworkId;
+    name: string;
+    hasAppRouter?: boolean;
+    packagePaths: string[];
+}
+export declare function detectFramework(cwd: string): Promise<DetectedFramework>;

package/dist/detect.js

@@ -0,0 +1,54 @@
+/**
+ * Framework and stack detection for Doctor.
+ * Supports: Next.js App Router, generic React, SvelteKit, Astro.
+ */
+import { readFile } from "fs/promises";
+import { existsSync } from "fs";
+import { join } from "path";
+const NEXT_APP_ROUTER_MARKERS = ["app/layout.tsx", "app/layout.js", "app/page.tsx", "app/page.js"];
+export async function detectFramework(cwd) {
+    const pkgPath = join(cwd, "package.json");
+    if (!existsSync(pkgPath)) {
+        return { id: "none", name: "None", packagePaths: [] };
+    }
+    const raw = await readFile(pkgPath, "utf-8");
+    let pkg;
+    try {
+        pkg = JSON.parse(raw);
+    }
+    catch {
+        return { id: "none", name: "None", packagePaths: [] };
+    }
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    if (deps["next"]) {
+        const hasAppRouter = NEXT_APP_ROUTER_MARKERS.some((m) => existsSync(join(cwd, m)));
+        return {
+            id: "next",
+            name: hasAppRouter ? "Next.js (App Router)" : "Next.js",
+            hasAppRouter,
+            packagePaths: ["@restormel/keys", "@restormel/keys-react"],
+        };
+    }
+    if (deps["@sveltejs/kit"]) {
+        return {
+            id: "sveltekit",
+            name: "SvelteKit",
+            packagePaths: ["@restormel/keys", "@restormel/keys-svelte"],
+        };
+    }
+    if (deps["astro"]) {
+        return {
+            id: "astro",
+            name: "Astro",
+            packagePaths: ["@restormel/keys", "@restormel/keys-elements"],
+        };
+    }
+    if (deps["react"] || deps["react-dom"]) {
+        return {
+            id: "react",
+            name: "React",
+            packagePaths: ["@restormel/keys", "@restormel/keys-react"],
+        };
+    }
+    return { id: "none", name: "None", packagePaths: ["@restormel/keys"] };
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+/**
+ * @restormel/doctor — standalone OSS healthcheck entrypoint.
+ */
+import { Command } from "commander";
+import chalk from "chalk";
+import { existsSync } from "fs";
+import { join } from "path";
+import { detectFramework } from "./detect.js";
+import { readConfig, CONFIG_FILENAME } from "./config.js";
+import { readStore } from "./store.js";
+function toExitCode(report) {
+    return report.ok ? 0 : 1;
+}
+function writeOutput(report, format) {
+    if (format === "json") {
+        process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+        return;
+    }
+    console.log(chalk.cyan("Restormel Doctor"));
+    console.log("");
+    for (const c of report.checks) {
+        const icon = c.status === "ok" ? chalk.green("✓") : c.status === "warn" ? chalk.yellow("○") : chalk.red("✗");
+        const label = chalk.white(c.label);
+        const msg = c.message ? chalk.gray(`— ${c.message}`) : "";
+        console.log(`${icon} ${label} ${msg}`.trimEnd());
+    }
+    console.log("");
+    console.log(report.ok ? chalk.green("OK") : chalk.red("Issues found"));
+}
+async function runDoctor() {
+    const cwd = process.cwd();
+    const checks = [];
+    const detected = await detectFramework(cwd);
+    checks.push({
+        id: "framework",
+        label: "Framework detection",
+        status: detected.id === "none" ? "warn" : "ok",
+        message: detected.name,
+        details: { id: detected.id, hasAppRouter: detected.hasAppRouter ?? false },
+    });
+    const config = await readConfig(cwd);
+    checks.push({
+        id: "config",
+        label: CONFIG_FILENAME,
+        status: config ? "ok" : "fail",
+        message: config ? "found" : "not found (run keys init)",
+        details: config ?? undefined,
+    });
+    const missingPkgs = [];
+    for (const p of detected.packagePaths) {
+        const pkgPath = join(cwd, "node_modules", p);
+        const found = existsSync(pkgPath);
+        if (!found)
+            missingPkgs.push(p);
+    }
+    checks.push({
+        id: "packages",
+        label: "Suggested Restormel packages",
+        status: missingPkgs.length === 0 ? "ok" : "fail",
+        message: missingPkgs.length === 0 ? "installed" : `missing: ${missingPkgs.join(", ")}`,
+        details: { suggested: detected.packagePaths, missing: missingPkgs },
+    });
+    const store = await readStore(cwd);
+    checks.push({
+        id: "keys",
+        label: "Local key store",
+        status: store.keys.length === 0 ? "warn" : "ok",
+        message: store.keys.length === 0 ? "no keys stored" : `${store.keys.length} key(s) stored`,
+        details: {
+            keys: store.keys.map((k) => ({ id: k.id, provider: k.provider, mask: k.mask, label: k.label })),
+        },
+    });
+    const ok = checks.every((c) => c.status !== "fail");
+    return { ok, cwd, checks };
+}
+async function main() {
+    const program = new Command();
+    program
+        .name("restormel-doctor")
+        .description("Restormel Doctor — open-source CLI for setup and health checks")
+        .version("0.1.0")
+        .option("--format <format>", "Output format: text|json", "text")
+        .option("--out <path>", "Write JSON output to a file (requires --format json)");
+    program.parse();
+    const opts = program.opts();
+    const format = (opts.format ?? "text");
+    if (format !== "text" && format !== "json") {
+        console.error(chalk.red("Invalid --format. Use text or json."));
+        process.exit(2);
+    }
+    if (opts.out && format !== "json") {
+        console.error(chalk.red("--out requires --format json."));
+        process.exit(2);
+    }
+    try {
+        const report = await runDoctor();
+        if (opts.out) {
+            const { writeFile } = await import("fs/promises");
+            await writeFile(opts.out, JSON.stringify(report, null, 2) + "\n", "utf-8");
+        }
+        writeOutput(report, format);
+        process.exit(toExitCode(report));
+    }
+    catch (e) {
+        console.error(chalk.red("Doctor failed:"), e instanceof Error ? e.message : String(e));
+        process.exit(2);
+    }
+}
+void main();

package/dist/store.d.ts

@@ -0,0 +1,15 @@
+export declare const STORE_DIR = ".restormel";
+export declare const STORE_FILENAME = "key-store.json";
+export interface StoredKey {
+    id: string;
+    provider: string;
+    label?: string;
+    /** Masked for display only (e.g. sk-...abc). Never log or expose. */
+    mask?: string;
+}
+export interface KeyStoreData {
+    keys: Array<StoredKey & {
+        apiKey: string;
+    }>;
+}
+export declare function readStore(cwd: string): Promise<KeyStoreData>;

package/dist/store.js

@@ -0,0 +1,25 @@
+/**
+ * Local key store. Lives under .restormel/ and must be in .gitignore.
+ * Contains secrets; never commit. Doctor never prints raw keys.
+ */
+import { readFile } from "fs/promises";
+import { existsSync } from "fs";
+import { join } from "path";
+export const STORE_DIR = ".restormel";
+export const STORE_FILENAME = "key-store.json";
+function storePath(cwd) {
+    return join(cwd, STORE_DIR, STORE_FILENAME);
+}
+export async function readStore(cwd) {
+    const path = storePath(cwd);
+    if (!existsSync(path))
+        return { keys: [] };
+    try {
+        const raw = await readFile(path, "utf-8");
+        const data = JSON.parse(raw);
+        return Array.isArray(data.keys) ? data : { keys: [] };
+    }
+    catch {
+        return { keys: [] };
+    }
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@restormel/doctor",
+  "version": "0.1.0",
+  "description": "Restormel Doctor — open-source CLI for setup and health checks.",
+  "keywords": [
+    "restormel",
+    "doctor",
+    "healthcheck",
+    "cli",
+    "byok",
+    "llm"
+  ],
+  "author": "Allotment Technology Ltd",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Allotment-Technology-Ltd/restormel-keys.git"
+  },
+  "homepage": "https://github.com/Allotment-Technology-Ltd/restormel-keys#readme",
+  "bugs": {
+    "url": "https://github.com/Allotment-Technology-Ltd/restormel-keys/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "restormel-doctor": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "typescript": "^5.7.2",
+    "vitest": "^4.1.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}