flowmo 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Izam Basiron
+
+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,131 @@
+# flowmo
+
+The local, zero-infrastructure prototyping engine for OutSystems-Lite workflows.
+
+Flowmo provides a lightning-fast, offline-first development environment to rapidly prototype screens, test complex SQL logic, and design workflows before ever touching an OutSystems Developer Cloud (ODC) environment.
+
+Powered by [PGLite](https://pglite.dev/) (WASM PostgreSQL) — no containers, no servers, no cloud dependencies.
+
+## Quick Start
+
+Scaffold a new project with [`create-flowmo`](https://www.npmjs.com/package/create-flowmo), then install `flowmo` inside it:
+
+```bash
+npx create-flowmo
+```
+
+You'll be prompted for a project name, target platform, and app type. Then:
+
+```bash
+cd my-prototype
+npm install
+```
+
+The generated project already has `flowmo` listed as a dependency and the `database/` folder pre-configured.
+
+## Commands
+
+### `flowmo db:setup`
+
+Reads `database/schema.sql`, drops the existing schema, and provisions the local database from scratch.
+
+```bash
+npx flowmo db:setup
+```
+
+Run this any time you change your schema.
+
+### `flowmo db:seed`
+
+Reads `database/seeds.sql` and inserts dummy data.
+
+```bash
+npx flowmo db:seed
+```
+
+### `flowmo db:query <file> [params-json]`
+
+Executes a `.sql` or `.advance.sql` file against the local database and prints results as an ASCII table.
+
+**Standard SQL:**
+```bash
+npx flowmo db:query database/queries/get_users.sql
+```
+
+**OutSystems Advanced SQL** (`.advance.sql`) with parameters:
+```bash
+npx flowmo db:query database/queries/get_user.advance.sql '{"UserId": 1, "Status": true}'
+```
+
+The Advanced SQL parser handles OutSystems syntax automatically:
+
+| OutSystems syntax | Translated to |
+|---|---|
+| `{Entity}.[Attribute]` | `entity.attribute` |
+| `{Entity}` | `entity` |
+| `@ParamName` | `$1`, `$2`, … |
+
+**Example `.advance.sql`:**
+```sql
+SELECT {Users}.[Name], {Users}.[Email]
+FROM {Users}
+WHERE {Users}.[Id] = @UserId AND {Users}.[IsActive] = @Status
+```
+
+**Output:**
+```
+┌─────────┬──────────────────┐
+│ Name    │ Email            │
+├─────────┼──────────────────┤
+│ Izam B. │ izam@example.com │
+└─────────┴──────────────────┘
+(1 row)
+```
+
+## Project Structure
+
+A scaffolded Flowmo project looks like this:
+
+```
+my-prototype/
+├── database/
+│   ├── schema.sql          # DDL — your single source of truth
+│   ├── seeds.sql           # Dummy data for UI prototyping
+│   └── queries/            # .sql and .advance.sql files
+├── logic/                  # .flowchart.md server action flows
+├── screens/                # .visual.html UI prototypes
+├── theme/                  # OutSystems UI CSS
+└── .flowmo/                # Local database (auto-generated, gitignored)
+    └── database/
+```
+
+## The AI Bridge (ODC to Flowmo)
+
+Because ODC restricts direct database access, the recommended workflow to mirror your schema locally is:
+
+1. Open ODC Service Studio and ask **Mentor AI** to generate a PostgreSQL `CREATE TABLE` script from your data model.
+2. Paste the output into `database/schema.sql`.
+3. Run `npx flowmo db:setup`.
+
+If you have the Flowmo Copilot skills installed (bundled by `create-flowmo`), your AI assistant can generate the schema directly from a description or screenshot of your ODC data model.
+
+## VS Code Ecosystem
+
+Flowmo CLI works alongside the Flowmo VS Code extensions:
+
+- **[Flowmo Visual Inspector](https://marketplace.visualstudio.com/items?itemName=flowmo.flowmo-visual-inspector)** — Live layer panel and element inspector for `.visual.html` screens.
+- **[Flowmo Flowchart Editor](https://marketplace.visualstudio.com/items?itemName=flowmo.flowmo-flowchart-editor)** — Drag-and-drop node editor for `.flowchart.md` server action flows.
+- **[PGlite Explorer](https://marketplace.visualstudio.com/search?term=pglite&target=VSCode)** (third-party) — Browse your `.flowmo/database` tables and run queries directly in VS Code.
+
+Install the Visual Inspector and Flowchart Editor together with the **[Flowmo Extension Pack](https://marketplace.visualstudio.com/items?itemName=flowmo.flowmo-extension-pack)**.
+
+## Links and Support
+
+- Web: [flowmo.lol](https://flowmo.lol)
+- Issues: [GitHub Issues](https://github.com/izambasiron/flowmo/issues)
+- Email: [support@flowmo.lol](mailto:support@flowmo.lol)
+- Support model: best-effort, no response-time guarantee
+
+## License
+
+MIT

package/bin/flowmo.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+import picocolors from 'picocolors';
+
+const [, , command, ...args] = process.argv;
+
+const HELP = `
+${picocolors.cyan(`
+      ___       ___           ___ 
+     /\\__\\     /\\  \\         /\\__\\
+    /:/  /    /::\\  \\       /:/  /
+   /:/  /    /:/\\:\\  \\     /:/  / 
+  /:/  /    /:/  \\:\\  \\   /:/  /  
+ /:/__/    /:/__/ \\:\\__\\ /:/__/   
+ \\:\\  \\    \\:\\  \\ /:/  / \\:\\  \\   
+  \\:\\  \\    \\:\\  /:/  /   \\:\\  \\  
+   \\:\\  \\    \\:\\/:/  /     \\:\\  \\ 
+    \\:\\__\\    \\::/  /       \\:\\__\\
+     \\/__/     \\/__/         \\/__/
+`)}
+${picocolors.bold('Flowmo CLI')} — Local prototyping engine for OutSystems-Lite workflows.
+
+${picocolors.bold('Usage:')}
+  flowmo <command> [options]
+
+${picocolors.bold('Commands:')}
+  ${picocolors.cyan('db:setup')}                          Reset and provision the local database from database/schema.sql
+  ${picocolors.cyan('db:seed')}                           Insert seed data from database/seeds.sql
+  ${picocolors.cyan('db:query')} <file> [params-json]     Execute a .sql or .advance.sql query file
+                                   ${picocolors.dim('--limit <n>')}  Max rows to show (default: 10)
+                                   ${picocolors.dim('--simple')}     Plain key: value output, no truncation
+
+${picocolors.bold('Examples:')}
+  flowmo db:setup
+  flowmo db:seed
+  flowmo db:query database/queries/get_users.sql
+  flowmo db:query database/queries/get_user.advance.sql '{"UserId": 1}'
+  flowmo db:query database/queries/get_users.sql --limit 25
+  flowmo db:query database/queries/get_users.sql --simple
+`;
+
+async function run() {
+  if (!command || command === '--help' || command === '-h') {
+    console.log(HELP);
+    process.exit(command ? 1 : 0);
+  }
+
+  const { dbSetup } = await import('../src/commands/db-setup.js');
+  const { dbSeed } = await import('../src/commands/db-seed.js');
+  const { dbQuery } = await import('../src/commands/db-query.js');
+
+  const commands = {
+    'db:setup': () => dbSetup(),
+    'db:seed': () => dbSeed(),
+    // Join all args after the file path in case the shell splits the JSON string.
+    'db:query': () => dbQuery(args),
+  };
+
+  if (!commands[command]) {
+    console.error(picocolors.red(`Unknown command: ${command}`));
+    console.log(HELP);
+    process.exit(1);
+  }
+
+  try {
+    await commands[command]();
+  } catch (err) {
+    console.error(picocolors.red(`\nError: ${err.message}`));
+    process.exit(1);
+  }
+}
+
+run();

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "flowmo",
+  "version": "0.1.0",
+  "description": "Local, zero-infrastructure prototyping engine for OutSystems-Lite workflows",
+  "type": "module",
+  "license": "MIT",
+  "author": {
+    "name": "Flowmo",
+    "email": "support@flowmo.lol"
+  },
+  "homepage": "https://flowmo.lol",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/izambasiron/flowmo"
+  },
+  "bugs": {
+    "url": "https://github.com/izambasiron/flowmo/issues"
+  },
+  "keywords": [
+    "outsystems",
+    "flowmo",
+    "pglite",
+    "postgres",
+    "prototyping",
+    "low-code"
+  ],
+  "bin": {
+    "flowmo": "./bin/flowmo.js"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "dependencies": {
+    "@electric-sql/pglite": "^0.2.0",
+    "cli-table3": "^0.6.3",
+    "picocolors": "^1.1.0"
+  }
+}

package/src/commands/db-query.js

@@ -0,0 +1,127 @@
+import fs from 'fs';
+import path from 'path';
+import picocolors from 'picocolors';
+import { getDb, closeDb } from '../lib/db.js';
+import { parseAdvancedSql } from '../lib/parser.js';
+import { renderTable } from '../lib/table.js';
+
+/**
+ * Parse a JSON parameter string from the shell.
+ *
+ * On Windows, cmd.exe (invoked via npx) strips double quotes from arguments,
+ * turning {"Key":"val"} into {Key:val}. This helper attempts to recover by
+ * re-quoting bare keys and string values before parsing.
+ */
+function parseJsonArg(raw) {
+  if (!raw) return {};
+
+  // 1. Try strict JSON first — covers correctly-quoted input.
+  try {
+    return JSON.parse(raw);
+  } catch {}
+
+  // 2. Try to restore quotes stripped by Windows cmd.exe.
+  try {
+    const fixed = raw
+      // Restore empty strings collapsed to a lone " by cmd.exe:  Key: ",  or  Key: "}
+      .replace(/:\s*"(\s*[,}])/g, ': ""$1')
+      // Quote unquoted object keys:  {Key:  or  ,Key:
+      .replace(/([{,]\s*)([A-Za-z_$][A-Za-z0-9_$-]*)\s*:/g, '$1"$2":')
+      // Restore empty string values stripped by cmd.exe:  "key":,  or  "key":}
+      .replace(/("[\w$-]+":\s*)(,|})/g, (m, key, end) => `${key}""${end}`)
+      // Quote unquoted string values (leave numbers, booleans, null untouched)
+      .replace(/:\s*([^",{\[\]}\s][^,}\]]*?)(\s*[,}])/g, (m, val, end) => {
+        const t = val.trim();
+        if (t === 'true' || t === 'false' || t === 'null' || /^-?\d+(\.\d+)?$/.test(t)) {
+          return m;
+        }
+        return `:"${t}"${end}`;
+      });
+    return JSON.parse(fixed);
+  } catch {}
+
+  throw new Error(
+    `Could not parse parameters as JSON.\nReceived: ${raw}\n\n` +
+    `On Windows PowerShell, wrap the JSON in single quotes:\n` +
+    `  '{"Key":"Value"}'`
+  );
+}
+
+export async function dbQuery(rawArgs = []) {
+  // Parse flags: --simple, --limit <n> / --limit=<n>
+  let simple = false;
+  let limit = 10;
+  const positional = [];
+
+  for (let i = 0; i < rawArgs.length; i++) {
+    const a = rawArgs[i];
+    if (a === '--simple') {
+      simple = true;
+    } else if (a === '--limit') {
+      limit = Math.max(1, parseInt(rawArgs[++i], 10) || 10);
+    } else if (a.startsWith('--limit=')) {
+      limit = Math.max(1, parseInt(a.slice(8), 10) || 10);
+    } else {
+      positional.push(a);
+    }
+  }
+
+  const filePath = positional[0];
+  const paramsJson = positional.length > 1 ? positional.slice(1).join(' ') : undefined;
+
+  if (!filePath) {
+    throw new Error('Usage: flowmo db:query <file> [params-json] [--limit <n>] [--simple]');
+  }
+
+  const resolved = path.resolve(process.cwd(), filePath);
+
+  if (!fs.existsSync(resolved)) {
+    throw new Error(`File not found: ${filePath}`);
+  }
+
+  const rawSql = fs.readFileSync(resolved, 'utf-8').trim();
+
+  if (!rawSql) {
+    throw new Error(`Query file is empty: ${filePath}`);
+  }
+
+  const isAdvanced = resolved.endsWith('.advance.sql');
+  let sql = rawSql;
+  let params = [];
+
+  if (isAdvanced) {
+    // Parse OutSystems syntax and map named @params to Postgres positional bindings.
+    const { sql: parsedSql, paramNames } = parseAdvancedSql(rawSql);
+    sql = parsedSql;
+
+    if (paramNames.length > 0) {
+      const paramsObj = paramsJson ? parseJsonArg(paramsJson) : {};
+
+      // Validate all required params are supplied.
+      const missing = paramNames.filter((n) => !(n in paramsObj));
+      if (missing.length > 0) {
+        throw new Error(
+          `Missing required parameter(s): ${missing.map((n) => `@${n}`).join(', ')}\n` +
+          `Pass them as a JSON string, e.g.: '${JSON.stringify(
+            Object.fromEntries(paramNames.map((n) => [n, '...']))
+          )}'`
+        );
+      }
+
+      params = paramNames.map((n) => paramsObj[n]);
+
+      const binding = paramNames.map((n, i) => `@${n} → $${i + 1}`).join(', ');
+      console.log(picocolors.dim(`Bindings: ${binding}\n`));
+    }
+  } else if (paramsJson) {
+    // For plain .sql files, accept a JSON array of positional params.
+    const parsed = parseJsonArg(paramsJson);
+    params = Array.isArray(parsed) ? parsed : Object.values(parsed);
+  }
+
+  const db = await getDb();
+  const result = await db.query(sql, params);
+  await closeDb();
+
+  renderTable(result.fields, result.rows, { simple, limit });
+}

package/src/commands/db-seed.js

@@ -0,0 +1,37 @@
+import fs from 'fs';
+import path from 'path';
+import picocolors from 'picocolors';
+import { getDb, closeDb } from '../lib/db.js';
+
+function resolveFile(filename) {
+  const candidates = [
+    path.join(process.cwd(), 'database', filename),
+    path.join(process.cwd(), filename),
+  ];
+  return candidates.find((p) => fs.existsSync(p)) ?? null;
+}
+
+export async function dbSeed() {
+  const seedsPath = resolveFile('seeds.sql');
+
+  if (!seedsPath) {
+    throw new Error(
+      'seeds.sql not found. Looked in database/seeds.sql and ./seeds.sql.\nAre you in a Flowmo project directory?'
+    );
+  }
+
+  const seeds = fs.readFileSync(seedsPath, 'utf-8').trim();
+
+  if (!seeds) {
+    throw new Error(`${seedsPath} is empty. Add your INSERT statements first.`);
+  }
+
+  console.log(picocolors.cyan('Seeding database…'));
+  console.log(picocolors.dim(`Using: ${seedsPath}`));
+
+  const db = await getDb();
+  await db.exec(seeds);
+  await closeDb();
+
+  console.log(picocolors.green(`✓ Database seeded from ${seedsPath}`));
+}

package/src/commands/db-setup.js

@@ -0,0 +1,43 @@
+import fs from 'fs';
+import path from 'path';
+import picocolors from 'picocolors';
+import { getDb, closeDb } from '../lib/db.js';
+
+function resolveFile(filename) {
+  const candidates = [
+    path.join(process.cwd(), 'database', filename),
+    path.join(process.cwd(), filename),
+  ];
+  return candidates.find((p) => fs.existsSync(p)) ?? null;
+}
+
+export async function dbSetup() {
+  const schemaPath = resolveFile('schema.sql');
+
+  if (!schemaPath) {
+    throw new Error(
+      'schema.sql not found. Looked in database/schema.sql and ./schema.sql.\nAre you in a Flowmo project directory?'
+    );
+  }
+
+  const schema = fs.readFileSync(schemaPath, 'utf-8').trim();
+
+  if (!schema) {
+    throw new Error(`${schemaPath} is empty. Add your CREATE TABLE statements first.`);
+  }
+
+  console.log(picocolors.cyan('Setting up database…'));
+  console.log(picocolors.dim(`Using: ${schemaPath}`));
+
+  const db = await getDb();
+
+  // Wipe the public schema so all user objects are removed cleanly.
+  await db.exec('DROP SCHEMA public CASCADE; CREATE SCHEMA public;');
+
+  // Apply the user-provided DDL.
+  await db.exec(schema);
+
+  await closeDb();
+
+  console.log(picocolors.green(`✓ Database schema applied from ${schemaPath}`));
+}

package/src/lib/db.js

@@ -0,0 +1,36 @@
+import { PGlite } from '@electric-sql/pglite';
+import fs from 'fs';
+import path from 'path';
+
+let _db = null;
+
+export function getDbPath() {
+  return path.join(process.cwd(), '.flowmo', 'database');
+}
+
+/**
+ * Returns a singleton PGlite instance, initialised and ready to query.
+ * Data is persisted to <cwd>/.flowmo/database.
+ */
+export async function getDb() {
+  if (_db) return _db;
+
+  const dbPath = getDbPath();
+  fs.mkdirSync(dbPath, { recursive: true });
+
+  _db = new PGlite(dbPath);
+  await _db.waitReady;
+
+  return _db;
+}
+
+/**
+ * Close the singleton database connection.
+ * Call at the end of a command to release file locks.
+ */
+export async function closeDb() {
+  if (_db) {
+    await _db.close();
+    _db = null;
+  }
+}

package/src/lib/parser.js

@@ -0,0 +1,105 @@
+/**
+ * Converts a PascalCase or camelCase identifier to snake_case.
+ * Examples:
+ *   RollingWeek       -> rolling_week
+ *   WorkLog           -> work_log
+ *   SSRClient         -> ssr_client
+ *   NonBillableRefId  -> non_billable_ref_id
+ *   TaskRoleId        -> task_role_id
+ */
+function toSnakeCase(str) {
+  return str
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1_$2')
+    .replace(/([a-z\d])([A-Z])/g, '$1_$2')
+    .toLowerCase();
+  // NOTE: trailing underscores are preserved intentionally.
+  // e.g. NonBillableRefTaskId_ → non_billable_ref_task_id_
+  // rolling_week uses trailing _ to disambiguate from identically-named columns on other tables.
+}
+
+/**
+ * Parses an OutSystems Advanced SQL file into standard PostgreSQL.
+ *
+ * Transformations applied (in order):
+ *   {Entity}.[Attribute]  ->  entity_name.attribute_name  (snake_case)
+ *   {Entity}              ->  entity_name                 (snake_case)
+ *   AS PascalAlias        ->  AS snake_alias              (CTE cols + table aliases)
+ *   alias.[Attribute]     ->  snake_alias.attribute_name  (snake_case both sides)
+ *   [Identifier]          ->  identifier                  (standalone bracket refs)
+ *   @ParamName            ->  $1, $2, ...                 (first-appearance order)
+ *
+ * Returns { sql: string, paramNames: string[] } where paramNames[i] is the
+ * original @-prefixed name that maps to positional binding $(i+1).
+ */
+export function parseAdvancedSql(sql) {
+  // 1. Replace {Entity}.[Attribute] with snake_case table and column
+  // 'user' is a PostgreSQL reserved word; quote it so it resolves to our view.
+  let parsed = sql.replace(/\{(\w+)\}\.\[(\w+)\]/g, (_, entity, attr) => {
+    const table = toSnakeCase(entity);
+    return `${table === 'user' ? '"user"' : table}.${toSnakeCase(attr)}`;
+  });
+
+  // 2. Replace bare {Entity} (table reference without attribute)
+  parsed = parsed.replace(/\{(\w+)\}/g, (_, entity) => {
+    const name = toSnakeCase(entity);
+    return name === 'user' ? '"user"' : name;
+  });
+
+  // 3a. Convert CTE definition names in WITH clause to snake_case.
+  //     The name comes BEFORE "AS", so it must be handled separately.
+  //     e.g. WITH TimesheetSkeleton AS ( -> WITH timesheet_skeleton AS (
+  parsed = parsed.replace(/\bWITH\s+([A-Z][A-Za-z0-9]+)\s+AS\b/g, (_, name) => {
+    return `WITH ${toSnakeCase(name)} AS`;
+  });
+
+  // 3b. Convert bare "AS PascalCase" aliases to snake_case.
+  //    Applies to CTE column aliases and table aliases in JOINs.
+  //    e.g. NULL::bigint AS NonBillableRefTaskId -> AS non_billable_ref_task_id
+  //         LEFT JOIN ref_task AS NBRefTask      -> AS nb_ref_task
+  //    Bracket aliases (AS [Col]) are left for step 5.
+  parsed = parsed.replace(/\b(?:AS|as)\s+([A-Z][A-Za-z0-9]+)\b/g, (_, alias) => {
+    return `AS ${toSnakeCase(alias)}`;
+  });
+
+  // 4. Replace alias.[Attribute] bracket notation still remaining.
+  //    Lowercases the alias prefix too so it matches the snake_case alias
+  //    defined in step 3.
+  //    e.g. TimesheetSkeleton.[TaskId] -> timesheetskeleton.task_id
+  //         NBRefTask.[Id]             -> nb_ref_task.id
+  parsed = parsed.replace(/(\w+)\.\[(\w+)\]/g, (_, alias, attr) => {
+    return `${toSnakeCase(alias)}.${toSnakeCase(attr)}`;
+  });
+
+  // 5. Replace remaining standalone [Identifier] brackets
+  //    e.g. AS [Row_UniqueId] -> AS row_uniqueid
+  //         ORDER BY [Col]    -> ORDER BY col
+  parsed = parsed.replace(/\[(\w+)\]/g, (_, name) => {
+    return name.toLowerCase();
+  });
+
+  // 6. Collect @params in order of first appearance and replace with $N.
+  //    Must run BEFORE the bare PascalCase step so that @UserId is captured
+  //    as "UserId" and not converted to "user_id" first.
+  const paramNames = [];
+  const paramIndex = {};
+
+  parsed = parsed.replace(/@(\w+)/g, (_, name) => {
+    if (!(name in paramIndex)) {
+      paramNames.push(name);
+      paramIndex[name] = paramNames.length;
+    }
+    return `$${paramIndex[name]}`;
+  });
+
+  // 7. Convert any remaining bare PascalCase identifiers to snake_case.
+  //    Catches CTE name references like FROM TimesheetSkeleton that have no
+  //    dot or brackets. SQL keywords are ALL CAPS and never match because
+  //    the regex requires at least one lowercase letter in the word.
+  //    @params are already replaced with $N so they are safe.
+  //    e.g. FROM TimesheetSkeleton -> FROM timesheet_skeleton
+  parsed = parsed.replace(/\b([A-Z][a-zA-Z0-9]*[a-z][a-zA-Z0-9]*)\b/g, (_, name) => {
+    return toSnakeCase(name);
+  });
+
+  return { sql: parsed, paramNames };
+}

package/src/lib/table.js

@@ -0,0 +1,72 @@
+import Table from 'cli-table3';
+import picocolors from 'picocolors';
+
+const TERMINAL_WIDTH = process.stdout.columns || 120;
+const KEY_COL_WIDTH = 28;
+const VAL_COL_WIDTH = TERMINAL_WIDTH - KEY_COL_WIDTH - 7; // 7 = borders + padding
+
+// Outer frame + vertical divider only — no horizontal inner lines
+const CHARS = {
+  top: '─', 'top-mid': '─', 'top-left': '┌', 'top-right': '┐',
+  bottom: '─', 'bottom-mid': '─', 'bottom-left': '└', 'bottom-right': '┘',
+  left: '│', 'left-mid': '', mid: '', 'mid-mid': '',
+  right: '│', 'right-mid': '',
+  middle: '│',
+};
+
+function formatVal(val) {
+  if (val === null || val === undefined) return picocolors.dim('NULL');
+  if (val instanceof Date) return val.toISOString().slice(0, 10);
+  if (typeof val === 'string' && /^\d{4}-\d{2}-\d{2}T/.test(val)) return val.slice(0, 10);
+  return String(val);
+}
+
+function truncate(str, maxLen) {
+  if (str.length <= maxLen) return str;
+  return str.slice(0, maxLen - 1) + '…';
+}
+
+/**
+ * Renders query results as a vertical key/value block per row.
+ *
+ * @param {Array<{ name: string }>} fields
+ * @param {Array<Record<string, unknown>>} rows
+ * @param {{ simple?: boolean, limit?: number }} opts
+ */
+export function renderTable(fields, rows, { simple = false, limit = 10 } = {}) {
+  if (rows.length === 0) {
+    console.log(picocolors.dim('(0 rows)'));
+    return;
+  }
+
+  const total = rows.length;
+  const displayed = rows.slice(0, limit);
+
+  if (simple) {
+    displayed.forEach((row, i) => {
+      console.log(picocolors.dim(`-[ Row ${i + 1} ]` + '-'.repeat(30)));
+      for (const f of fields) {
+        console.log(`${picocolors.bold(f.name)}: ${formatVal(row[f.name])}`);
+      }
+    });
+  } else {
+    displayed.forEach((row, i) => {
+      console.log(picocolors.dim(`-[ Row ${i + 1} ]` + '-'.repeat(30)));
+      const table = new Table({
+        chars: CHARS,
+        style: { head: [], border: ['grey'] },
+        colWidths: [KEY_COL_WIDTH, VAL_COL_WIDTH],
+      });
+      for (const f of fields) {
+        table.push([picocolors.bold(f.name), truncate(formatVal(row[f.name]), VAL_COL_WIDTH - 2)]);
+      }
+      console.log(table.toString());
+    });
+  }
+
+  const rowLabel = `(${displayed.length} row${displayed.length !== 1 ? 's' : ''})`;
+  const limitNote = total > limit
+    ? picocolors.yellow(` — showing ${limit} of ${total}, use --limit to change`)
+    : '';
+  console.log(picocolors.dim(rowLabel) + limitNote);
+}