chore: import upstream snapshot with attribution

examples/typescript/postgres/postgres.ts

@@ -0,0 +1,81 @@
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import dotenv from 'dotenv'
+import { MountMode, PostgresResource, Workspace } from '@struktoai/mirage-node'
+
+dotenv.config({ path: '.env.development' })
+
+const dsn = process.env.POSTGRES_DSN
+if (dsn === undefined) {
+  console.error('POSTGRES_DSN missing in .env.development')
+  process.exit(1)
+}
+
+const resource = new PostgresResource({ dsn })
+const ws = new Workspace({ '/pg/': resource }, { mode: MountMode.READ })
+
+const DEC = new TextDecoder()
+
+async function run(label: string, cmd: string): Promise<void> {
+  console.log(`\n=== ${label} ===`)
+  const r = await ws.execute(cmd)
+  if (r.exitCode !== 0) {
+    console.log(`(exit=${String(r.exitCode)})`)
+    if (r.stderr.byteLength > 0) console.log(DEC.decode(r.stderr))
+    if (r.stdout.byteLength > 0) console.log(DEC.decode(r.stdout))
+    return
+  }
+  process.stdout.write(DEC.decode(r.stdout))
+  if (!DEC.decode(r.stdout).endsWith('\n')) process.stdout.write('\n')
+}
+
+try {
+  await run('ls /pg', 'ls /pg')
+
+  await run('cat /pg/database.json (head)', 'head -n 20 /pg/database.json')
+
+  const dirOut = await ws.execute('ls /pg/public/tables')
+  const tables = DEC.decode(dirOut.stdout).split('\n').filter((s) => s.length > 0)
+  if (tables.length === 0) {
+    console.log('\nno tables in public schema; stopping')
+  } else {
+    const target = tables[0]!
+    const dir = `/pg/public/tables/${target}`
+
+    await run(`ls ${dir}`, `ls ${dir}`)
+    await run('stat schema.json', `stat ${dir}/schema.json`)
+    await run('stat rows.jsonl', `stat ${dir}/rows.jsonl`)
+    await run('cat schema.json', `cat ${dir}/schema.json`)
+    await run('head -n 3 rows.jsonl', `head -n 3 ${dir}/rows.jsonl`)
+    await run('tail -n 2 rows.jsonl', `tail -n 2 ${dir}/rows.jsonl`)
+    await run('wc -l rows.jsonl', `wc -l ${dir}/rows.jsonl`)
+    await run('grep ":" /pg/public/tables (top-level pushdown)', `grep -c ":" ${dir}/rows.jsonl`)
+    await run('jq .name schema.json', `jq ".name" ${dir}/schema.json`)
+    await run('find /pg/public -maxdepth 2', 'find /pg/public -maxdepth 2')
+    await run('tree -L 2 /pg/public', 'tree -L 2 /pg/public')
+
+    await run(
+      'cat rows.jsonl (size guard fires for huge tables)',
+      `cat ${dir}/rows.jsonl | wc -l`,
+    )
+  }
+
+  console.log('\n=== ops summary ===')
+  // workspace exposes ops counts via internal observer; we just confirm we got here cleanly.
+  console.log('all commands completed')
+} finally {
+  await ws.close()
+  await resource.close()
+}

examples/typescript/postgres/postgres_fuse.ts

@@ -0,0 +1,101 @@
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import { readdir, stat } from "node:fs/promises";
+import dotenv from "dotenv";
+import {
+  Mount,
+  MountMode,
+  PostgresResource,
+  Workspace,
+} from "@struktoai/mirage-node";
+
+dotenv.config({ path: ".env.development" });
+
+const dsn = process.env.POSTGRES_DSN;
+if (dsn === undefined) {
+  console.error("POSTGRES_DSN missing in .env.development");
+  process.exit(1);
+}
+
+const DEC = new TextDecoder();
+
+async function main(): Promise<void> {
+  const resource = new PostgresResource({
+    dsn,
+    maxReadRows: 1_000_000,
+    maxReadBytes: 512 * 1024 * 1024,
+  });
+  const ws = new Workspace({
+    "/pg/": new Mount(resource, { mode: MountMode.READ, fuse: true }),
+  });
+  await ws.fuseReady();
+  const mp = ws.fuseMountpoint as string;
+
+  try {
+    console.log(`\n=== FUSE MODE: mounted at ${mp} ===\n`);
+
+    console.log("--- fs.readdir() root ---");
+    for (const e of (await readdir(mp)).sort()) console.log(`  ${e}`);
+
+    console.log("\n--- ws.execute(cat database.json | jq .schemas) ---");
+    const r1 = await ws.execute('cat /pg/database.json | jq ".schemas"');
+    process.stdout.write(DEC.decode(r1.stdout));
+
+    const tables = (await readdir(`${mp}/public/tables`)).sort();
+    console.log(`\n--- public.tables: ${String(tables.length)} entries ---`);
+    for (const t of tables.slice(0, 5)) console.log(`  ${t}`);
+
+    if (tables.length === 0) return;
+    const target = tables[0]!;
+    const dir = `/pg/public/tables/${target}`;
+    const hostDir = `${mp}/public/tables/${target}`;
+
+    console.log(`\n--- fs.readdir(${hostDir}) ---`);
+    for (const e of await readdir(hostDir)) console.log(`  ${e}`);
+
+    console.log(`\n--- fs.stat(${hostDir}/rows.jsonl) ---`);
+    const st = await stat(`${hostDir}/rows.jsonl`);
+    console.log(
+      `  size=${String(st.size)} type=${st.isFile() ? "file" : "dir"}`,
+    );
+
+    console.log(`\n--- ws.execute(jq .name ${dir}/schema.json) ---`);
+    const r2 = await ws.execute(`jq ".name" ${dir}/schema.json`);
+    process.stdout.write(DEC.decode(r2.stdout));
+
+    console.log(`\n--- ws.execute(head -n 1 ${dir}/rows.jsonl) ---`);
+    const r3 = await ws.execute(`head -n 1 ${dir}/rows.jsonl`);
+    process.stdout.write(DEC.decode(r3.stdout).slice(0, 200));
+    console.log("...");
+
+    console.log(`\n--- ws.execute(wc -l ${dir}/rows.jsonl) ---`);
+    const r4 = await ws.execute(`wc -l ${dir}/rows.jsonl`);
+    process.stdout.write(DEC.decode(r4.stdout));
+
+    console.log(`\n>>> FUSE mounted at: ${mp}`);
+    console.log(">>> You can open another terminal and try:");
+    console.log(`>>>   ls ${mp}/`);
+    console.log(`>>>   cat ${mp}/database.json | jq .schemas`);
+    console.log(`>>>   head -n 3 ${mp}/public/tables/${target}/rows.jsonl`);
+    console.log(
+      ">>> Auto-unmounting now (run interactively for manual exploration).",
+    );
+  } finally {
+    await ws.close();
+    await resource.close();
+  }
+}
+
+await main();

examples/typescript/postgres/postgres_vfs.ts

@@ -0,0 +1,85 @@
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import dotenv from 'dotenv'
+import { MountMode, PostgresResource, Workspace } from '@struktoai/mirage-node'
+
+dotenv.config({ path: '.env.development' })
+
+const dsn = process.env.POSTGRES_DSN
+if (dsn === undefined) {
+  console.error('POSTGRES_DSN missing in .env.development')
+  process.exit(1)
+}
+
+const DEC = new TextDecoder()
+
+async function dump(ws: Workspace, label: string, cmd: string): Promise<void> {
+  console.log(`\n--- ${label} ---`)
+  const r = await ws.execute(cmd)
+  if (r.exitCode !== 0) {
+    console.log(`(exit=${String(r.exitCode)}) ${DEC.decode(r.stderr)}`)
+    return
+  }
+  process.stdout.write(DEC.decode(r.stdout))
+  if (!DEC.decode(r.stdout).endsWith('\n')) process.stdout.write('\n')
+}
+
+async function main(): Promise<void> {
+  const resource = new PostgresResource({
+    dsn,
+    maxReadRows: 200,
+    maxReadBytes: 1024 * 1024,
+  })
+  const ws = new Workspace({ '/pg/': resource }, { mode: MountMode.READ })
+
+  try {
+    console.log('=== VFS MODE: shell pipelines transparently read Postgres ===')
+
+    await dump(ws, 'ls /pg — root entries', 'ls /pg')
+    await dump(ws, 'ls /pg/public', 'ls /pg/public')
+    await dump(ws, 'ls /pg/public/tables (first 5)', 'ls /pg/public/tables | head -n 5')
+
+    const tablesOut = await ws.execute('ls /pg/public/tables')
+    const tables = DEC.decode(tablesOut.stdout).split('\n').filter((s) => s.length > 0)
+    if (tables.length === 0) {
+      console.log('\nno tables in public; stopping')
+      return
+    }
+
+    const target = tables[0]!
+    const dir = `/pg/public/tables/${target}`
+
+    await dump(ws, `ls ${dir}`, `ls ${dir}`)
+    await dump(ws, 'cat database.json | jq .schemas', 'cat /pg/database.json | jq ".schemas"')
+    await dump(ws, `jq .name ${dir}/schema.json`, `jq ".name" ${dir}/schema.json`)
+    await dump(ws, `head -n 1 ${dir}/rows.jsonl`, `head -n 1 ${dir}/rows.jsonl`)
+    await dump(ws, `wc -l ${dir}/rows.jsonl`, `wc -l ${dir}/rows.jsonl`)
+    await dump(
+      ws,
+      `cat ${dir}/rows.jsonl (size guard fires for large tables)`,
+      `cat ${dir}/rows.jsonl | wc -l`,
+    )
+    await dump(
+      ws,
+      `grep -c context ${dir}/rows.jsonl`,
+      `grep -c context ${dir}/rows.jsonl`,
+    )
+  } finally {
+    await ws.close()
+    await resource.close()
+  }
+}
+
+await main()