@hamzaashergill/mateos 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MateOS contributors
+
+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,158 @@
+# MateOS
+
+MateOS is an open-source assistant operations platform for teams that manage bookings, appointments, reception workflows, and customer communication.
+
+It currently ships with starter patterns for:
+
+- Restaurants and food
+- Dental and doctors
+- Coaches and consultants
+
+MateOS includes:
+
+- A React admin dashboard for operators
+- An Express API server
+- PostgreSQL persistence with Drizzle ORM
+- AI-assisted scheduling, conversation relay, and workflow tools
+- Optional Microsoft, Twilio, ElevenLabs, Hume, and Telegram integrations
+
+## Short Install Command
+
+Once the CLI is published to npm, the short install command is:
+
+```bash
+npx mateos
+```
+
+Or install into a custom directory:
+
+```bash
+npx mateos my-mateos
+```
+
+## GitHub Install
+
+Today, the GitHub bootstrap command is:
+
+```bash
+bash <(curl -fsSL https://raw.githubusercontent.com/logicbaseio/MateOS/main/install.sh)
+```
+
+Both install paths do the same bootstrap work:
+
+- clones the MateOS repo locally
+- creates `.env` from `.env.example`
+- installs workspace dependencies with `pnpm`
+- starts PostgreSQL with Docker Compose
+- applies the database schema
+- shows the MateOS terminal logo and next steps
+
+After install, MateOS also ships with a local CLI:
+
+```bash
+cd MateOS
+node ./bin/mateos.mjs doctor
+node ./bin/mateos.mjs dev
+```
+
+## Workspace Layout
+
+```text
+MateOS/
+├── artifacts/api-server        # Express API
+├── artifacts/bot-manager       # React dashboard
+├── lib/db                      # Database schema and Drizzle config
+├── lib/api-spec                # OpenAPI contract
+├── lib/api-client-react        # Generated frontend client
+├── lib/api-zod                 # Generated API schemas
+├── docs                        # Open-source documentation
+└── starter-configs             # Vertical starter templates
+```
+
+## Quick Start
+
+### 1. Install dependencies
+
+```bash
+pnpm install
+```
+
+### 2. Start PostgreSQL
+
+```bash
+docker compose up -d
+```
+
+### 3. Create your local env file
+
+```bash
+cp .env.example .env
+```
+
+### 4. Push the schema
+
+```bash
+pnpm db:push
+```
+
+### 5. Start the API
+
+```bash
+pnpm dev:api
+```
+
+### 6. Start the dashboard
+
+```bash
+pnpm dev:web
+```
+
+Open [http://localhost:5173](http://localhost:5173).
+
+### 7. Or start both with the MateOS CLI
+
+```bash
+node ./bin/mateos.mjs dev
+```
+
+## Authentication Modes
+
+MateOS now supports an installable default path:
+
+- `MATEOS_AUTH_MODE=local`
+  Default. Local single-admin mode for self-hosting and development.
+- `MATEOS_AUTH_MODE=oidc`
+  Optional generic OIDC mode for teams that want hosted sign-in.
+
+When using OIDC, set:
+
+- `OIDC_CLIENT_ID`
+- `OIDC_ISSUER_URL`
+- optional provider-specific secrets as needed
+
+## Vertical Starter Configs
+
+Starter templates live in [`starter-configs/`](./starter-configs).
+
+- [restaurant-food.json](./starter-configs/restaurant-food.json)
+- [dental-doctors.json](./starter-configs/dental-doctors.json)
+- [coaches-consultants.json](./starter-configs/coaches-consultants.json)
+
+Use them as starting points for:
+
+- default assistant naming
+- scheduling windows
+- intake rules
+- customer notes
+- workflow tone
+
+## Repository Notes
+
+- The scheduling/reception stack is the primary MateOS surface.
+- The alerts/routing module is still present and can be reused as a general operations inbox.
+- Some internal concepts still use `boss` naming in code and database fields. That is behavioral debt, not a blocker for open-source release.
+
+## Docs
+
+- [Open Source Audit](./docs/open-source-audit.md)
+- [Architecture](./docs/architecture.md)

package/bin/mateos

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "./mateos.mjs";

package/bin/mateos.mjs

@@ -0,0 +1,273 @@
+#!/usr/bin/env node
+
+import { copyFileSync, existsSync, readFileSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { dirname, resolve, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const DEFAULT_REPO_URL = "https://github.com/logicbaseio/MateOS.git";
+const GREEN = "\x1b[38;5;46m";
+const CYAN = "\x1b[38;5;51m";
+const DIM = "\x1b[2m";
+const RESET = "\x1b[0m";
+
+const LOGO = [
+  "##   ##   ####   #####  ######   ####    ####",
+  "### ###  ##  ##    ##   ##      ##  ##  ##",
+  "## # ##  ######    ##   ####    ##  ##   ####",
+  "##   ##  ##  ##    ##   ##      ##  ##      ##",
+  "##   ##  ##  ##    ##   ######   ####    ####",
+];
+
+function printLogo() {
+  process.stdout.write(`\n${GREEN}${LOGO.join("\n")}${RESET}\n`);
+  process.stdout.write(`${CYAN}MateOS${RESET} ${DIM}assistant operations platform${RESET}\n\n`);
+}
+
+function printUsage() {
+  printLogo();
+  console.log("Usage: mateos [directory]");
+  console.log("   or: mateos <command>");
+  console.log("");
+  console.log("Commands:");
+  console.log("  create   Clone and bootstrap MateOS locally");
+  console.log("  logo     Show the MateOS terminal logo");
+  console.log("  init     Create .env from .env.example if needed");
+  console.log("  doctor   Check local prerequisites");
+  console.log("  dev      Start API and dashboard together");
+}
+
+function runCommand(command, args, options = {}) {
+  return new Promise((resolvePromise, rejectPromise) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd ?? process.cwd(),
+      stdio: "inherit",
+      shell: false,
+      ...options,
+    });
+
+    child.on("error", rejectPromise);
+    child.on("exit", (code, signal) => {
+      if (signal) {
+        rejectPromise(new Error(`${command} exited via signal ${signal}`));
+        return;
+      }
+      resolvePromise(code ?? 0);
+    });
+  });
+}
+
+function findProjectRoot(startDir) {
+  let current = resolve(startDir);
+  while (true) {
+    const pkgPath = join(current, "package.json");
+    const workspacePath = join(current, "pnpm-workspace.yaml");
+    const apiPath = join(current, "artifacts", "api-server");
+    if (existsSync(pkgPath) && existsSync(workspacePath) && existsSync(apiPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+        if (pkg?.name === "mateos") return current;
+      } catch {
+        return current;
+      }
+    }
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+function requireProjectRoot() {
+  const projectRoot = findProjectRoot(process.cwd());
+  if (!projectRoot) {
+    console.error("This command must be run inside a MateOS checkout.");
+    console.error("Use `npx mateos` first to create one.");
+    process.exit(1);
+  }
+  return projectRoot;
+}
+
+async function ensurePnpm() {
+  try {
+    await runCommand("pnpm", ["--version"], { stdio: "pipe" });
+    return;
+  } catch {
+    try {
+      await runCommand("corepack", ["enable"]);
+      await runCommand("corepack", ["prepare", "pnpm@latest", "--activate"]);
+    } catch {
+      console.error("pnpm is required. Install pnpm or enable it through corepack.");
+      process.exit(1);
+    }
+  }
+}
+
+async function commandCreate(targetDir = "MateOS") {
+  printLogo();
+  const repoUrl = process.env.MATEOS_REPO_URL ?? DEFAULT_REPO_URL;
+
+  if (existsSync(resolve(process.cwd(), targetDir))) {
+    console.error(`Target already exists: ${targetDir}`);
+    process.exit(1);
+  }
+
+  for (const [command, args] of [["git", ["--version"]], ["node", ["--version"]], ["docker", ["--version"]]]) {
+    try {
+      await runCommand(command, args, { stdio: "pipe" });
+    } catch {
+      console.error(`Missing required command: ${command}`);
+      process.exit(1);
+    }
+  }
+
+  await ensurePnpm();
+
+  console.log(`Cloning MateOS into ${targetDir}`);
+  await runCommand("git", ["clone", repoUrl, targetDir]);
+
+  const projectRoot = resolve(process.cwd(), targetDir);
+  const envPath = resolve(projectRoot, ".env");
+  const envExamplePath = resolve(projectRoot, ".env.example");
+  if (!existsSync(envPath) && existsSync(envExamplePath)) {
+    copyFileSync(envExamplePath, envPath);
+    console.log("Created .env from .env.example");
+  }
+
+  console.log("Installing workspace dependencies");
+  await runCommand("pnpm", ["install"], { cwd: projectRoot });
+
+  console.log("Starting PostgreSQL with Docker Compose");
+  await runCommand("docker", ["compose", "up", "-d"], { cwd: projectRoot });
+
+  console.log("Applying database schema");
+  await runCommand("pnpm", ["db:push"], { cwd: projectRoot });
+
+  console.log("");
+  console.log("MateOS is installed.");
+  console.log(`Next steps:`);
+  console.log(`  cd ${targetDir}`);
+  console.log("  node ./bin/mateos.mjs doctor");
+  console.log("  node ./bin/mateos.mjs dev");
+}
+
+async function commandInit() {
+  printLogo();
+  const root = requireProjectRoot();
+  const envPath = resolve(root, ".env");
+  const envExamplePath = resolve(root, ".env.example");
+
+  if (existsSync(envPath)) {
+    console.log(".env already exists. Nothing changed.");
+    return;
+  }
+
+  copyFileSync(envExamplePath, envPath);
+  console.log("Created .env from .env.example");
+}
+
+async function commandDoctor() {
+  printLogo();
+  const root = requireProjectRoot();
+
+  const checks = [
+    ["node", ["--version"]],
+    ["pnpm", ["--version"]],
+    ["docker", ["--version"]],
+  ];
+
+  let failed = false;
+
+  for (const [command, args] of checks) {
+    try {
+      const code = await runCommand(command, args, { cwd: root, stdio: "pipe" });
+      if (code === 0) {
+        console.log(`${command}: ok`);
+      } else {
+        failed = true;
+        console.log(`${command}: failed`);
+      }
+    } catch {
+      failed = true;
+      console.log(`${command}: missing`);
+    }
+  }
+
+  console.log("");
+  if (failed) {
+    console.log("Install the missing prerequisites, then rerun `mateos doctor`.");
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log("Local prerequisites look good.");
+}
+
+async function commandDev() {
+  printLogo();
+  const root = requireProjectRoot();
+  if (!existsSync(resolve(root, ".env"))) {
+    copyFileSync(resolve(root, ".env.example"), resolve(root, ".env"));
+    console.log("Created .env from .env.example");
+  }
+
+  const api = spawn("pnpm", ["dev:api"], {
+    cwd: root,
+    stdio: "inherit",
+    shell: false,
+  });
+
+  const web = spawn("pnpm", ["dev:web"], {
+    cwd: root,
+    stdio: "inherit",
+    shell: false,
+  });
+
+  const shutdown = (code = 0) => {
+    api.kill("SIGTERM");
+    web.kill("SIGTERM");
+    process.exit(code);
+  };
+
+  process.on("SIGINT", () => shutdown(0));
+  process.on("SIGTERM", () => shutdown(0));
+
+  api.on("exit", (code) => {
+    if (code && code !== 0) shutdown(code);
+  });
+
+  web.on("exit", (code) => {
+    if (code && code !== 0) shutdown(code);
+  });
+}
+
+const firstArg = process.argv[2];
+const knownCommands = new Set(["create", "logo", "init", "doctor", "dev", "help", "--help", "-h"]);
+const command = knownCommands.has(firstArg ?? "") ? firstArg : "create";
+const createTarget = command === "create" && firstArg && !knownCommands.has(firstArg) ? firstArg : process.argv[3];
+
+switch (command) {
+  case "create":
+    await commandCreate(createTarget || "MateOS");
+    break;
+  case "logo":
+    printLogo();
+    break;
+  case "init":
+    await commandInit();
+    break;
+  case "doctor":
+    await commandDoctor();
+    break;
+  case "dev":
+    await commandDev();
+    break;
+  case "help":
+  case "--help":
+  case "-h":
+    printUsage();
+    break;
+  default:
+    printUsage();
+    process.exitCode = command === "usage" ? 0 : 1;
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@hamzaashergill/mateos",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "description": "MateOS bootstrap CLI and open-source assistant operations platform",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/logicbaseio/MateOS.git"
+  },
+  "homepage": "https://github.com/logicbaseio/MateOS",
+  "bugs": {
+    "url": "https://github.com/logicbaseio/MateOS/issues"
+  },
+  "keywords": [
+    "mateos",
+    "assistant",
+    "appointments",
+    "bookings",
+    "reception",
+    "scheduling"
+  ],
+  "bin": "bin/mateos",
+  "files": [
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "mateos": "node ./bin/mateos.mjs",
+    "dev:api": "pnpm --filter @workspace/api-server dev",
+    "dev:web": "pnpm --filter @workspace/bot-manager dev",
+    "db:push": "pnpm --filter @workspace/db push",
+    "codegen": "pnpm --filter @workspace/api-spec run codegen",
+    "build": "pnpm run typecheck && pnpm -r --if-present run build",
+    "typecheck:libs": "tsc --build",
+    "typecheck": "pnpm run typecheck:libs && pnpm -r --filter \"./artifacts/**\" --filter \"./scripts\" --if-present run typecheck"
+  },
+  "devDependencies": {
+    "prettier": "^3.8.1",
+    "typescript": "~5.9.2"
+  }
+}