@useatlas/create 0.0.2 → 0.0.4

package/templates/docker/bin/atlas.ts

@@ -28,6 +28,7 @@
  *   bun run atlas -- diff --tables t1,t2         # Diff only specific tables/views
  *   bun run atlas -- diff --schema analytics     # Diff a non-public PostgreSQL schema
  *   bun run atlas -- diff --source warehouse     # Diff from semantic/warehouse/ subdirectory
+ *   bun run atlas -- doctor                      # Validate environment and connectivity
  *
  * When run in a TTY without --tables or --demo, an interactive multiselect picker
  * lets you choose which tables and views to profile. --demo skips the picker since
@@ -44,7 +45,22 @@ import * as path from "path";
 import * as yaml from "js-yaml";
 import * as p from "@clack/prompts";
 import pc from "picocolors";
-import { detectDBType, type DBType } from "@atlas/api/lib/db/connection";
+import { type DBType } from "@atlas/api/lib/db/connection";
+
+/** CLI-local DB type detection — supports all URL schemes (core + plugin databases). */
+function detectDBType(url: string): DBType {
+  if (url.startsWith("postgresql://") || url.startsWith("postgres://")) return "postgres";
+  if (url.startsWith("mysql://") || url.startsWith("mysql2://")) return "mysql";
+  if (url.startsWith("clickhouse://") || url.startsWith("clickhouses://")) return "clickhouse";
+  if (url.startsWith("snowflake://")) return "snowflake";
+  if (url.startsWith("duckdb://")) return "duckdb";
+  if (url.startsWith("salesforce://")) return "salesforce";
+  const scheme = url.split("://")[0] || "(empty)";
+  throw new Error(
+    `Unsupported database URL scheme "${scheme}://". ` +
+    "Supported: postgresql://, mysql://, clickhouse://, snowflake://, duckdb://, salesforce://."
+  );
+}
 // Lazy-loaded to avoid requiring native bindings at type-check time
 async function loadDuckDB() {
   const { DuckDBInstance } = await import("@duckdb/node-api");
@@ -1051,7 +1067,7 @@ async function createSnowflakePool(connectionString: string, max = 1) {
   const snowflake = require("snowflake-sdk") as typeof import("snowflake-sdk");
   snowflake.configure({ logLevel: "ERROR" });
 
-  const { parseSnowflakeURL } = await import("@atlas/api/lib/db/connection");
+  const { parseSnowflakeURL } = await import("../../../plugins/snowflake/src/connection");
   const opts = parseSnowflakeURL(connectionString);
 
   const pool = snowflake.createPool(
@@ -1386,12 +1402,13 @@ function mapSalesforceFieldType(sfType: string): string {
 }
 
 export async function listSalesforceObjects(connectionString: string): Promise<DatabaseObject[]> {
-  const { parseSalesforceURL, createSalesforceDataSource } = await import("@atlas/api/lib/db/salesforce");
+  const { parseSalesforceURL, createSalesforceConnection } = await import("../../../plugins/salesforce/src/connection");
   const config = parseSalesforceURL(connectionString);
-  const source = createSalesforceDataSource(config);
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const source: any = createSalesforceConnection(config);
   try {
     const objects = await source.listObjects();
-    return objects.map((obj) => ({
+    return objects.map((obj: { name: string }) => ({
       name: obj.name,
       type: "table" as const,
     }));
@@ -1405,9 +1422,10 @@ export async function profileSalesforce(
   filterTables?: string[],
   prefetchedObjects?: DatabaseObject[],
 ): Promise<TableProfile[]> {
-  const { parseSalesforceURL, createSalesforceDataSource } = await import("@atlas/api/lib/db/salesforce");
+  const { parseSalesforceURL, createSalesforceConnection } = await import("../../../plugins/salesforce/src/connection");
   const config = parseSalesforceURL(connectionString);
-  const source = createSalesforceDataSource(config);
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const source: any = createSalesforceConnection(config);
 
   const profiles: TableProfile[] = [];
   const errors: { table: string; error: string }[] = [];
@@ -1418,7 +1436,7 @@ export async function profileSalesforce(
       allObjects = prefetchedObjects;
     } else {
       const objects = await source.listObjects();
-      allObjects = objects.map((obj) => ({
+      allObjects = objects.map((obj: { name: string }) => ({
         name: obj.name,
         type: "table" as const,
       }));
@@ -1452,7 +1470,8 @@ export async function profileSalesforce(
         const foreignKeys: ForeignKey[] = [];
         const primaryKeyColumns: string[] = [];
 
-        const columns: ColumnProfile[] = desc.fields.map((field) => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const columns: ColumnProfile[] = desc.fields.map((field: any) => {
           const isPK = field.name === "Id";
           if (isPK) primaryKeyColumns.push(field.name);
 
@@ -1470,7 +1489,8 @@ export async function profileSalesforce(
 
           // For picklist fields, extract active values as sample_values
           const sampleValues = isEnumLike
-            ? field.picklistValues.filter((pv) => pv.active).map((pv) => pv.value)
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            ? field.picklistValues.filter((pv: any) => pv.active).map((pv: any) => pv.value)
             : [];
 
           return {
@@ -2684,6 +2704,21 @@ function parseDemoArg(args: string[]): DemoDataset | null {
   throw new Error(`Unknown demo dataset "${next}". Available: ${Object.keys(DEMO_DATASETS).join(", ")}`);
 }
 
+/** Recursively copy a directory, overwriting existing files. */
+function copyDirRecursive(src: string, dest: string): void {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDirRecursive(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+      console.log(`  wrote ${destPath}`);
+    }
+  }
+}
+
 // --- Demo data seeding ---
 
 export async function seedDemoPostgres(
@@ -3134,7 +3169,7 @@ export async function handleActionApproval(
 
 interface PluginInfo {
   id: string;
-  type: string;
+  types: string[];
   version: string;
   name?: string;
   healthy?: boolean;
@@ -3169,7 +3204,7 @@ export async function handlePluginList(): Promise<void> {
   for (const p of plugins) {
     const info: PluginInfo = {
       id: String(p.id ?? "unknown"),
-      type: String(p.type ?? "unknown"),
+      types: Array.isArray(p.types) ? (p.types as string[]).map(String) : ["unknown"],
       version: String(p.version ?? "unknown"),
       name: p.name ? String(p.name) : undefined,
     };
@@ -3194,7 +3229,7 @@ export async function handlePluginList(): Promise<void> {
   const rows = infos.map((info) => ({
     Name: info.name ?? info.id,
     ID: info.id,
-    Type: info.type,
+    Type: info.types.join(", "),
     Version: info.version,
     Health:
       info.healthy === undefined
@@ -3230,7 +3265,7 @@ import type { AtlasDatasourcePlugin, PluginDBConnection } from "@useatlas/plugin
 
 export default definePlugin({
   id: "${id}",
-  type: "datasource",
+  types: ["datasource"],
   version: "0.1.0",
   name: "${pascalName}",
 
@@ -3259,7 +3294,7 @@ import type { AtlasContextPlugin } from "@useatlas/plugin-sdk";
 
 export default definePlugin({
   id: "${id}",
-  type: "context",
+  types: ["context"],
   version: "0.1.0",
   name: "${pascalName}",
 
@@ -3290,7 +3325,7 @@ import type { Hono } from "hono";
 
 export default definePlugin({
   id: "${id}",
-  type: "interaction",
+  types: ["interaction"],
   version: "0.1.0",
   name: "${pascalName}",
 
@@ -3317,7 +3352,7 @@ import { z } from "zod";
 
 export default definePlugin({
   id: "${id}",
-  type: "action",
+  types: ["action"],
   version: "0.1.0",
   name: "${pascalName}",
 
@@ -3358,7 +3393,7 @@ import type { AtlasSandboxPlugin, PluginExploreBackend, PluginExecResult } from
 
 export default definePlugin({
   id: "${id}",
-  type: "sandbox",
+  types: ["sandbox"],
   version: "0.1.0",
   name: "${pascalName}",
 
@@ -3398,7 +3433,7 @@ import plugin from "./index";
 describe("${name} plugin", () => {
   test("has correct id and type", () => {
     expect(plugin.id).toBe("${name}");
-    expect(plugin.type).toBe("${pluginType}");
+    expect(plugin.types).toContain("${pluginType}");
   });
 
   test("has a version string", () => {
@@ -3890,9 +3925,10 @@ async function handleDiff(args: string[]): Promise<void> {
       }
     }
   } else if (dbType === "salesforce") {
-    const { parseSalesforceURL, createSalesforceDataSource } = await import("@atlas/api/lib/db/salesforce");
+    const { parseSalesforceURL, createSalesforceConnection } = await import("../../../plugins/salesforce/src/connection");
     const config = parseSalesforceURL(connStr);
-    const source = createSalesforceDataSource(config);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const source: any = createSalesforceConnection(config);
     try {
       const objects = await source.listObjects();
       console.log(`Connected: Salesforce (${objects.length} queryable objects)`);
@@ -3949,7 +3985,7 @@ async function handleDiff(args: string[]): Promise<void> {
         profiles = await profileSnowflake(connStr, filterTables);
         break;
       case "duckdb": {
-        const { parseDuckDBUrl } = await import("@atlas/api/lib/db/duckdb");
+        const { parseDuckDBUrl } = await import("../../../plugins/duckdb/src/connection");
         const duckConfig = parseDuckDBUrl(connStr);
         profiles = await profileDuckDB(duckConfig.path, filterTables);
         break;
@@ -3958,8 +3994,7 @@ async function handleDiff(args: string[]): Promise<void> {
         profiles = await profileSalesforce(connStr, filterTables);
         break;
       default: {
-        const _exhaustive: never = dbType;
-        throw new Error(`Unknown database type: ${_exhaustive}`);
+        throw new Error(`Unknown database type: ${dbType}`);
       }
     }
   } catch (err) {
@@ -4136,7 +4171,7 @@ async function profileDatasource(opts: ProfileDatasourceOpts): Promise<void> {
     }
   } else if (dbType === "duckdb") {
     try {
-      const { parseDuckDBUrl } = await import("@atlas/api/lib/db/duckdb");
+      const { parseDuckDBUrl } = await import("../../../plugins/duckdb/src/connection");
       const duckConfig = parseDuckDBUrl(connStr);
       const DuckDBInstance = await loadDuckDB();
       const testInstance = await DuckDBInstance.create(duckConfig.path, { access_mode: "READ_ONLY" });
@@ -4156,9 +4191,10 @@ async function profileDatasource(opts: ProfileDatasourceOpts): Promise<void> {
       process.exit(1);
     }
   } else if (dbType === "salesforce") {
-    const { parseSalesforceURL, createSalesforceDataSource } = await import("@atlas/api/lib/db/salesforce");
+    const { parseSalesforceURL, createSalesforceConnection } = await import("../../../plugins/salesforce/src/connection");
     const config = parseSalesforceURL(connStr);
-    const source = createSalesforceDataSource(config);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const source: any = createSalesforceConnection(config);
     try {
       const objects = await source.listObjects();
       console.log(`Connected: Salesforce (${objects.length} queryable objects)`);
@@ -4208,7 +4244,7 @@ async function profileDatasource(opts: ProfileDatasourceOpts): Promise<void> {
           allObjects = await listSnowflakeObjects(connStr);
           break;
         case "duckdb": {
-          const { parseDuckDBUrl } = await import("@atlas/api/lib/db/duckdb");
+          const { parseDuckDBUrl } = await import("../../../plugins/duckdb/src/connection");
           const duckConfig = parseDuckDBUrl(connStr);
           allObjects = await listDuckDBObjects(duckConfig.path);
           break;
@@ -4217,8 +4253,7 @@ async function profileDatasource(opts: ProfileDatasourceOpts): Promise<void> {
           allObjects = await listSalesforceObjects(connStr);
           break;
         default: {
-          const _exhaustive: never = dbType;
-          throw new Error(`Unknown database type: ${_exhaustive}`);
+          throw new Error(`Unknown database type: ${dbType}`);
         }
       }
     } catch (err) {
@@ -4278,7 +4313,7 @@ async function profileDatasource(opts: ProfileDatasourceOpts): Promise<void> {
       profiles = await profileSnowflake(connStr, selectedTables, prefetchedObjects);
       break;
     case "duckdb": {
-      const { parseDuckDBUrl } = await import("@atlas/api/lib/db/duckdb");
+      const { parseDuckDBUrl } = await import("../../../plugins/duckdb/src/connection");
       const duckConfig = parseDuckDBUrl(connStr);
       profiles = await profileDuckDB(duckConfig.path, selectedTables, prefetchedObjects);
       break;
@@ -4287,8 +4322,7 @@ async function profileDatasource(opts: ProfileDatasourceOpts): Promise<void> {
       profiles = await profileSalesforce(connStr, selectedTables, prefetchedObjects);
       break;
     default: {
-      const _exhaustive: never = dbType;
-      throw new Error(`Unknown database type: ${_exhaustive}`);
+      throw new Error(`Unknown database type: ${dbType}`);
     }
   }
 
@@ -4374,6 +4408,15 @@ async function profileDatasource(opts: ProfileDatasourceOpts): Promise<void> {
     }
   }
 
+  // For --demo simple, overlay hand-crafted semantic files with richer descriptions
+  if (demoDataset === "simple") {
+    const demoSemanticDir = path.resolve(import.meta.dir, "..", "data", "demo-semantic");
+    if (fs.existsSync(demoSemanticDir)) {
+      console.log(`\nApplying curated demo semantic layer...\n`);
+      copyDirRecursive(demoSemanticDir, outputBase);
+    }
+  }
+
   // LLM enrichment (optional)
   let enrichmentSucceeded = false;
   if (shouldEnrich) {
@@ -4551,6 +4594,24 @@ async function main() {
     return handleSmoke(args);
   }
 
+  if (command === "completions") {
+    const { handleCompletions } = await import("../src/completions");
+    handleCompletions(args);
+    return;
+  }
+
+  if (command === "doctor") {
+    const { runDoctor } = await import("../src/doctor");
+    const exitCode = await runDoctor();
+    process.exit(exitCode);
+  }
+
+  if (command === "validate") {
+    const { runValidate } = await import("../src/validate");
+    const exitCode = await runValidate();
+    process.exit(exitCode);
+  }
+
   if (command === "diff") {
     return handleDiff(args);
   }
@@ -4625,17 +4686,20 @@ async function main() {
 
   if (command !== "init") {
     console.log(
-      "Usage: bun run atlas -- <init|diff|query|eval|smoke|migrate|plugin|benchmark|mcp> [options]\n\n" +
+      "Usage: bun run atlas -- <init|diff|query|doctor|validate|eval|smoke|migrate|plugin|benchmark|mcp|completions> [options]\n\n" +
       "Commands:\n" +
-      "  init       Profile DB and generate semantic layer\n" +
-      "  diff       Compare DB schema against existing semantic layer\n" +
-      "  query      Ask a question via the Atlas API\n" +
-      "  eval       Run eval pipeline against demo schemas\n" +
-      "  smoke      Run E2E smoke tests against a running Atlas deployment\n" +
-      "  migrate    Generate/apply plugin schema migrations\n" +
-      "  plugin     Manage plugins (list, create, add)\n" +
-      "  benchmark  Run BIRD benchmark for text-to-SQL accuracy\n" +
-      "  mcp        Start MCP server (stdio default, --transport sse --port N for SSE)\n\n" +
+      "  init          Profile DB and generate semantic layer\n" +
+      "  diff          Compare DB schema against existing semantic layer\n" +
+      "  query         Ask a question via the Atlas API\n" +
+      "  doctor        Validate environment, connectivity, and configuration\n" +
+      "  validate      Check config and semantic layer YAML files (offline)\n" +
+      "  eval          Run eval pipeline against demo schemas\n" +
+      "  smoke         Run E2E smoke tests against a running Atlas deployment\n" +
+      "  migrate       Generate/apply plugin schema migrations\n" +
+      "  plugin        Manage plugins (list, create, add)\n" +
+      "  benchmark     Run BIRD benchmark for text-to-SQL accuracy\n" +
+      "  mcp           Start MCP server (stdio default, --transport sse --port N for SSE)\n" +
+      "  completions   Output shell completion script (bash, zsh, fish)\n\n" +
       "Options (init):\n" +
       "  --tables t1,t2         Only specific tables/views\n" +
       "  --schema <name>        PostgreSQL schema (default: public)\n" +
@@ -4645,7 +4709,7 @@ async function main() {
       "  --parquet f1.parquet[,...] Load Parquet files via DuckDB\n" +
       "  --enrich               Profile + LLM enrichment (needs API key)\n" +
       "  --no-enrich            Explicitly skip LLM enrichment\n" +
-      "  --demo [simple|cybersec]  Load demo dataset then profile\n\n" +
+      "  --demo [simple|cybersec|ecommerce]  Load demo dataset then profile\n\n" +
       "Options (diff):\n" +
       "  --tables t1,t2         Only diff specific tables/views\n" +
       "  --schema <name>        PostgreSQL schema (default: public)\n" +

package/templates/docker/data/demo-semantic/catalog.yml

@@ -1,40 +1,64 @@
-version: '1.0'
+version: "1.0"
+name: Atlas Demo — SaaS CRM
+description: |
+  B2B SaaS company CRM dataset. Tracks companies (customers), the people who work
+  there (contacts), and subscription accounts with plan tiers and MRR.
+  Use this dataset to explore revenue analysis, customer segmentation,
+  churn patterns, and org-level reporting.
+
 entities:
-  - name: Accounts
-    file: entities/accounts.yml
-    grain: one row per account record
-    description: accounts (80 rows, 7 columns)
-    use_for:
-      - Segmentation by plan, status
-      - Aggregation on monthly_value
-      - Cross-entity analysis via companies
-    common_questions:
-      - How many accounts by plan?
-      - How many accounts by status?
-      - What is the average monthly_value across accounts?
-      - How are accounts distributed across companies?
   - name: Companies
     file: entities/companies.yml
-    grain: one row per company record
-    description: companies (50 rows, 8 columns)
+    grain: one row per customer company
+    description: >
+      Customer companies with firmographic data — industry, headcount,
+      geography, revenue, and valuation.
     use_for:
-      - Aggregation on employee_count, founded_year, revenue, valuation
+      - Firmographic segmentation (industry, country, company size)
+      - Revenue and valuation analysis
+      - Customer base composition
     common_questions:
-      - What is the average employee_count across companies?
+      - What industries make up our customer base?
+      - Which countries have the most customers?
+      - What is the average company revenue by industry?
+      - How many enterprise-size companies (500+ employees) do we have?
+
   - name: People
     file: entities/people.yml
-    grain: one row per person record
-    description: people (198 rows, 8 columns)
+    grain: one row per contact
+    description: >
+      Contacts at customer companies — department, seniority, title,
+      and start date. Linked to companies via company_id.
+    use_for:
+      - Stakeholder mapping by department and seniority
+      - Org chart analysis per company
+      - Tenure and hiring trend analysis
+    common_questions:
+      - How many contacts do we have per company?
+      - What is the department breakdown across all contacts?
+      - Which companies have the most executive-level contacts?
+      - What seniority levels are most common?
+
+  - name: Accounts
+    file: entities/accounts.yml
+    grain: one row per subscription account
+    description: >
+      Subscription accounts with plan tier, billing status, MRR
+      (monthly_value), and contract dates. Linked to companies via company_id.
     use_for:
-      - Segmentation by department, seniority
-      - Cross-entity analysis via companies
+      - MRR and revenue analysis by plan
+      - Churn and retention analysis
+      - Contract lifecycle tracking
+      - Cross-entity analysis joining to companies and people
     common_questions:
-      - How many people by department?
-      - How many people by seniority?
-      - How are people distributed across companies?
+      - What is total MRR by plan type?
+      - How many accounts are churned vs active?
+      - What is the average contract length?
+      - Which companies have the highest MRR?
+
 glossary: glossary.yml
 metrics:
   - file: metrics/accounts.yml
-    description: Auto-generated metrics for accounts
+    description: Subscription and revenue metrics (MRR, churn rate, ARPA)
   - file: metrics/companies.yml
-    description: Auto-generated metrics for companies
+    description: Customer base metrics (count, avg revenue, industry breakdown)