instant-cli 0.22.156 → 0.22.157-branch-cli-query.22963745357.1

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> instant-cli@0.22.156 build /home/runner/work/instant/instant/client/packages/cli
+> instant-cli@0.22.157-branch-cli-query.22963745357.1 build /home/runner/work/instant/instant/client/packages/cli
 > rm -rf dist; tsc -p tsconfig.json
 

package/__tests__/e2e/cli.e2e.test.ts

@@ -1,7 +1,14 @@
 import { describe, it, expect } from 'vitest';
+import { randomUUID } from 'crypto';
 import { readFile } from 'fs/promises';
 import { join } from 'path';
-import { runCli, createTestProject, createTempApp } from './helpers';
+import {
+  runCli,
+  createTestProject,
+  createTempApp,
+  adminTransact,
+  createAppUser,
+} from './helpers';
 
 const SCHEMA_FILE = `
 import { i } from "@instantdb/core";
@@ -494,6 +501,521 @@ export default _schema;
     });
   });
 
+  describe('query', () => {
+    it('queries data from an app', async () => {
+      const { appId, adminToken } = await createTempApp();
+      const project = await createTestProject({
+        appId,
+        schemaFile: SCHEMA_FILE,
+      });
+
+      try {
+        const pushResult = await runCli(['push', 'schema', '--yes'], {
+          cwd: project.dir,
+          env: {
+            INSTANT_CLI_AUTH_TOKEN: adminToken,
+            INSTANT_APP_ID: appId,
+          },
+        });
+        expect(pushResult.exitCode).toBe(0);
+
+        await adminTransact(appId, adminToken, [
+          ['update', 'posts', randomUUID(), { title: 'Hello', body: 'World' }],
+          ['update', 'posts', randomUUID(), { title: 'Second', body: 'Post' }],
+        ]);
+
+        const result = await runCli(
+          ['query', '--admin', JSON.stringify({ posts: {} })],
+          {
+            cwd: project.dir,
+            env: {
+              INSTANT_CLI_AUTH_TOKEN: adminToken,
+              INSTANT_APP_ID: appId,
+            },
+          },
+        );
+
+        expect(result.exitCode).toBe(0);
+        const data = JSON.parse(result.stdout);
+        expect(data.posts).toHaveLength(2);
+        expect(data.posts.map((p: any) => p.title).sort()).toEqual([
+          'Hello',
+          'Second',
+        ]);
+      } finally {
+        await project.cleanup();
+      }
+    });
+
+    it('queries with filters', async () => {
+      const { appId, adminToken } = await createTempApp();
+      const project = await createTestProject({
+        appId,
+        schemaFile: SCHEMA_FILE,
+      });
+
+      try {
+        const pushResult = await runCli(['push', 'schema', '--yes'], {
+          cwd: project.dir,
+          env: {
+            INSTANT_CLI_AUTH_TOKEN: adminToken,
+            INSTANT_APP_ID: appId,
+          },
+        });
+        expect(pushResult.exitCode).toBe(0);
+
+        await adminTransact(appId, adminToken, [
+          ['update', 'posts', randomUUID(), { title: 'Match', body: 'Yes' }],
+          ['update', 'posts', randomUUID(), { title: 'Nope', body: 'No' }],
+        ]);
+
+        const query = {
+          posts: { $: { where: { title: 'Match' } } },
+        };
+        const result = await runCli(
+          ['query', '--admin', JSON.stringify(query)],
+          {
+            cwd: project.dir,
+            env: {
+              INSTANT_CLI_AUTH_TOKEN: adminToken,
+              INSTANT_APP_ID: appId,
+            },
+          },
+        );
+
+        expect(result.exitCode).toBe(0);
+        const data = JSON.parse(result.stdout);
+        expect(data.posts).toHaveLength(1);
+        expect(data.posts[0].title).toBe('Match');
+      } finally {
+        await project.cleanup();
+      }
+    });
+
+    it('returns empty arrays for entities with no data', async () => {
+      const { appId, adminToken } = await createTempApp();
+      const project = await createTestProject({
+        appId,
+        schemaFile: SCHEMA_FILE,
+      });
+
+      try {
+        const pushResult = await runCli(['push', 'schema', '--yes'], {
+          cwd: project.dir,
+          env: {
+            INSTANT_CLI_AUTH_TOKEN: adminToken,
+            INSTANT_APP_ID: appId,
+          },
+        });
+        expect(pushResult.exitCode).toBe(0);
+
+        const result = await runCli(
+          ['query', '--admin', JSON.stringify({ posts: {} })],
+          {
+            cwd: project.dir,
+            env: {
+              INSTANT_CLI_AUTH_TOKEN: adminToken,
+              INSTANT_APP_ID: appId,
+            },
+          },
+        );
+
+        expect(result.exitCode).toBe(0);
+        const data = JSON.parse(result.stdout);
+        expect(data.posts).toEqual([]);
+      } finally {
+        await project.cleanup();
+      }
+    });
+
+    it('works with --app flag', async () => {
+      const { appId, adminToken } = await createTempApp();
+      const project = await createTestProject({
+        schemaFile: SCHEMA_FILE,
+      });
+
+      try {
+        const pushResult = await runCli(
+          ['push', 'schema', '--app', appId, '--yes'],
+          {
+            cwd: project.dir,
+            env: { INSTANT_CLI_AUTH_TOKEN: adminToken },
+          },
+        );
+        expect(pushResult.exitCode).toBe(0);
+
+        const result = await runCli(
+          ['query', '--admin', '--app', appId, JSON.stringify({ posts: {} })],
+          {
+            cwd: project.dir,
+            env: { INSTANT_CLI_AUTH_TOKEN: adminToken },
+          },
+        );
+
+        expect(result.exitCode).toBe(0);
+        const data = JSON.parse(result.stdout);
+        expect(data.posts).toEqual([]);
+      } finally {
+        await project.cleanup();
+      }
+    });
+
+    it('fails with invalid JSON', async () => {
+      const { appId, adminToken } = await createTempApp();
+      const project = await createTestProject({ appId });
+
+      try {
+        const result = await runCli(['query', '--admin', 'not valid json'], {
+          cwd: project.dir,
+          env: {
+            INSTANT_CLI_AUTH_TOKEN: adminToken,
+            INSTANT_APP_ID: appId,
+          },
+        });
+
+        expect(result.exitCode).not.toBe(0);
+      } finally {
+        await project.cleanup();
+      }
+    });
+
+    it('fails without context flag', async () => {
+      const { appId, adminToken } = await createTempApp();
+      const project = await createTestProject({ appId });
+
+      try {
+        const result = await runCli(['query', JSON.stringify({ posts: {} })], {
+          cwd: project.dir,
+          env: {
+            INSTANT_CLI_AUTH_TOKEN: adminToken,
+            INSTANT_APP_ID: appId,
+          },
+        });
+
+        expect(result.exitCode).not.toBe(0);
+        const output = result.stdout + result.stderr;
+        expect(output).toMatch(/--admin|--as-email|--as-guest/);
+      } finally {
+        await project.cleanup();
+      }
+    });
+
+    it('fails with multiple context flags', async () => {
+      const { appId, adminToken } = await createTempApp();
+      const project = await createTestProject({ appId });
+
+      try {
+        const result = await runCli(
+          [
+            'query',
+            '--as-email',
+            'alice@example.com',
+            '--as-guest',
+            JSON.stringify({ posts: {} }),
+          ],
+          {
+            cwd: project.dir,
+            env: {
+              INSTANT_CLI_AUTH_TOKEN: adminToken,
+              INSTANT_APP_ID: appId,
+            },
+          },
+        );
+
+        expect(result.exitCode).not.toBe(0);
+        const output = result.stdout + result.stderr;
+        expect(output).toMatch(/exactly one context/);
+      } finally {
+        await project.cleanup();
+      }
+    });
+
+    it('fails without auth', async () => {
+      const { appId } = await createTempApp();
+      const project = await createTestProject({ appId });
+
+      try {
+        const result = await runCli(
+          ['query', '--admin', JSON.stringify({ posts: {} })],
+          {
+            cwd: project.dir,
+            env: {
+              INSTANT_CLI_AUTH_TOKEN: '',
+              INSTANT_APP_ADMIN_TOKEN: '',
+              INSTANT_ADMIN_TOKEN: '',
+              INSTANT_APP_ID: appId,
+            },
+          },
+        );
+
+        expect(result.exitCode).not.toBe(0);
+        const output = result.stdout + result.stderr;
+        expect(output).toMatch(/not logged in/i);
+      } finally {
+        await project.cleanup();
+      }
+    });
+
+    it('queries nested associations', async () => {
+      const { appId, adminToken } = await createTempApp();
+      const project = await createTestProject({
+        appId,
+        schemaFile: SCHEMA_FILE,
+      });
+
+      try {
+        const pushResult = await runCli(['push', 'schema', '--yes'], {
+          cwd: project.dir,
+          env: {
+            INSTANT_CLI_AUTH_TOKEN: adminToken,
+            INSTANT_APP_ID: appId,
+          },
+        });
+        expect(pushResult.exitCode).toBe(0);
+
+        const postId = randomUUID();
+        const commentId = randomUUID();
+        await adminTransact(appId, adminToken, [
+          ['update', 'posts', postId, { title: 'My Post', body: 'Content' }],
+          ['update', 'comments', commentId, { text: 'Great post!' }],
+          ['link', 'posts', postId, { comments: commentId }],
+        ]);
+
+        const result = await runCli(
+          ['query', '--admin', JSON.stringify({ posts: { comments: {} } })],
+          {
+            cwd: project.dir,
+            env: {
+              INSTANT_CLI_AUTH_TOKEN: adminToken,
+              INSTANT_APP_ID: appId,
+            },
+          },
+        );
+
+        expect(result.exitCode).toBe(0);
+        const data = JSON.parse(result.stdout);
+        expect(data.posts).toHaveLength(1);
+        expect(data.posts[0].comments).toHaveLength(1);
+        expect(data.posts[0].comments[0].text).toBe('Great post!');
+      } finally {
+        await project.cleanup();
+      }
+    });
+
+    it('--as-email runs query as a specific user with perms applied', async () => {
+      const { appId, adminToken } = await createTempApp();
+
+      const schemaWithCreator = `
+import { i } from "@instantdb/core";
+const _schema = i.schema({
+  entities: {
+    posts: i.entity({
+      title: i.string(),
+      creatorEmail: i.string(),
+    }),
+  },
+});
+export default _schema;
+`;
+
+      // Only allow users to view posts they created
+      const restrictedPerms = `export default {
+  posts: {
+    allow: {
+      view: "auth.email == data.creatorEmail",
+    },
+  },
+};
+`;
+
+      const project = await createTestProject({
+        appId,
+        schemaFile: schemaWithCreator,
+        permsFile: restrictedPerms,
+      });
+
+      try {
+        const pushResult = await runCli(['push', '--yes'], {
+          cwd: project.dir,
+          env: {
+            INSTANT_CLI_AUTH_TOKEN: adminToken,
+            INSTANT_APP_ID: appId,
+          },
+        });
+        expect(pushResult.exitCode).toBe(0);
+
+        await createAppUser(appId, adminToken, 'alice@test.com');
+        await createAppUser(appId, adminToken, 'bob@test.com');
+
+        await adminTransact(appId, adminToken, [
+          [
+            'update',
+            'posts',
+            randomUUID(),
+            { title: "Alice's Post", creatorEmail: 'alice@test.com' },
+          ],
+          [
+            'update',
+            'posts',
+            randomUUID(),
+            { title: "Bob's Post", creatorEmail: 'bob@test.com' },
+          ],
+        ]);
+
+        // Admin sees all posts
+        const adminResult = await runCli(
+          ['query', '--admin', JSON.stringify({ posts: {} })],
+          {
+            cwd: project.dir,
+            env: {
+              INSTANT_CLI_AUTH_TOKEN: adminToken,
+              INSTANT_APP_ID: appId,
+            },
+          },
+        );
+        expect(adminResult.exitCode).toBe(0);
+        const adminData = JSON.parse(adminResult.stdout);
+        expect(adminData.posts).toHaveLength(2);
+
+        // Alice only sees her post
+        const aliceResult = await runCli(
+          [
+            'query',
+            '--as-email',
+            'alice@test.com',
+            JSON.stringify({ posts: {} }),
+          ],
+          {
+            cwd: project.dir,
+            env: {
+              INSTANT_CLI_AUTH_TOKEN: adminToken,
+              INSTANT_APP_ID: appId,
+            },
+          },
+        );
+        expect(aliceResult.exitCode).toBe(0);
+        const aliceData = JSON.parse(aliceResult.stdout);
+        expect(aliceData.posts).toHaveLength(1);
+        expect(aliceData.posts[0].title).toBe("Alice's Post");
+
+        // Bob only sees his post
+        const bobResult = await runCli(
+          [
+            'query',
+            '--as-email',
+            'bob@test.com',
+            JSON.stringify({ posts: {} }),
+          ],
+          {
+            cwd: project.dir,
+            env: {
+              INSTANT_CLI_AUTH_TOKEN: adminToken,
+              INSTANT_APP_ID: appId,
+            },
+          },
+        );
+        expect(bobResult.exitCode).toBe(0);
+        const bobData = JSON.parse(bobResult.stdout);
+        expect(bobData.posts).toHaveLength(1);
+        expect(bobData.posts[0].title).toBe("Bob's Post");
+      } finally {
+        await project.cleanup();
+      }
+    });
+
+    it('--as-guest runs query as unauthenticated user', async () => {
+      const { appId, adminToken } = await createTempApp();
+
+      // Guests can only see posts marked as public
+      const schemaWithVisibility = `
+import { i } from "@instantdb/core";
+const _schema = i.schema({
+  entities: {
+    posts: i.entity({
+      title: i.string(),
+      isPublic: i.boolean(),
+    }),
+  },
+});
+export default _schema;
+`;
+
+      const guestPerms = `export default {
+  posts: {
+    allow: {
+      view: "data.isPublic == true",
+    },
+  },
+};
+`;
+
+      const project = await createTestProject({
+        appId,
+        schemaFile: schemaWithVisibility,
+        permsFile: guestPerms,
+      });
+
+      try {
+        const pushResult = await runCli(['push', '--yes'], {
+          cwd: project.dir,
+          env: {
+            INSTANT_CLI_AUTH_TOKEN: adminToken,
+            INSTANT_APP_ID: appId,
+          },
+        });
+        expect(pushResult.exitCode).toBe(0);
+
+        await adminTransact(appId, adminToken, [
+          [
+            'update',
+            'posts',
+            randomUUID(),
+            { title: 'Public Post', isPublic: true },
+          ],
+          [
+            'update',
+            'posts',
+            randomUUID(),
+            { title: 'Private Post', isPublic: false },
+          ],
+        ]);
+
+        // Admin sees both
+        const adminResult = await runCli(
+          ['query', '--admin', JSON.stringify({ posts: {} })],
+          {
+            cwd: project.dir,
+            env: {
+              INSTANT_CLI_AUTH_TOKEN: adminToken,
+              INSTANT_APP_ID: appId,
+            },
+          },
+        );
+        expect(adminResult.exitCode).toBe(0);
+        const adminData = JSON.parse(adminResult.stdout);
+        expect(adminData.posts).toHaveLength(2);
+
+        // Guest only sees public post
+        const guestResult = await runCli(
+          ['query', '--as-guest', JSON.stringify({ posts: {} })],
+          {
+            cwd: project.dir,
+            env: {
+              INSTANT_CLI_AUTH_TOKEN: adminToken,
+              INSTANT_APP_ID: appId,
+            },
+          },
+        );
+        expect(guestResult.exitCode).toBe(0);
+        const guestData = JSON.parse(guestResult.stdout);
+        expect(guestData.posts).toHaveLength(1);
+        expect(guestData.posts[0].title).toBe('Public Post');
+      } finally {
+        await project.cleanup();
+      }
+    });
+  });
+
   describe('info', () => {
     it('shows version', async () => {
       const result = await runCli(['info']);

package/__tests__/e2e/helpers.ts

@@ -114,6 +114,50 @@ export async function createTestProject(
   };
 }
 
+export async function adminTransact(
+  appId: string,
+  adminToken: string,
+  steps: any[],
+): Promise<void> {
+  const response = await fetch(`${apiUrl}/admin/transact`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${adminToken}`,
+      'app-id': appId,
+    },
+    body: JSON.stringify({ steps }),
+  });
+  if (!response.ok) {
+    throw new Error(
+      `Failed to transact: ${response.status} ${await response.text()}`,
+    );
+  }
+}
+
+export async function createAppUser(
+  appId: string,
+  adminToken: string,
+  email: string,
+): Promise<{ userId: string; refreshToken: string }> {
+  const response = await fetch(`${apiUrl}/admin/refresh_tokens`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${adminToken}`,
+      'app-id': appId,
+    },
+    body: JSON.stringify({ email }),
+  });
+  if (!response.ok) {
+    throw new Error(
+      `Failed to create user: ${response.status} ${await response.text()}`,
+    );
+  }
+  const data = await response.json();
+  return { userId: data.user.id, refreshToken: data.user.refresh_token };
+}
+
 export async function createTempApp(title = 'cli-e2e-test'): Promise<{
   appId: string;
   adminToken: string;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.js"],"names":[],"mappings":"AAwhEA,8EAQC;AA+ED;;;;;EAKE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.js"],"names":[],"mappings":"AAgnEA,8EAQC;AA+ED;;;;;EAKE"}

package/dist/index.js

@@ -5,6 +5,7 @@ import { mkdir, writeFile, readFile, unlink } from 'fs/promises';
 import path, { join } from 'path';
 import { randomUUID } from 'crypto';
 import jsonDiff from 'json-diff';
+import JSON5 from 'json5';
 import chalk from 'chalk';
 import { program, Option } from 'commander';
 import boxen from 'boxen';
@@ -419,6 +420,17 @@ program
     }
     openInBrowser(`${instantDashOrigin}/dash?s=main&app=${appId}&t=explorer`);
 });
+program
+    .command('query')
+    .argument('<query>', 'InstaQL query as JSON')
+    .option('-a --app <app-id>', 'App ID to query. Defaults to *_INSTANT_APP_ID in .env')
+    .option('--admin', 'Run the query as admin (bypasses permissions)')
+    .option('--as-email <email>', 'Run the query as a specific user by email')
+    .option('--as-guest', 'Run the query as an unauthenticated guest')
+    .description('Run an InstaQL query against your app.')
+    .action(async function (queryArg, opts) {
+    await handleQuery(queryArg, opts);
+});
 program.parse(process.argv);
 async function handleInit(opts) {
     const pkgAndAuthInfo = await getOrPromptPackageAndAuthInfoWithErrorLogging(opts);
@@ -496,6 +508,66 @@ async function handleInitWithoutFiles(opts) {
         process.exit(1);
     }
 }
+async function detectAppIdQuietly(opts) {
+    const fromOpts = await detectAppIdFromOptsWithErrorLogging(opts);
+    if (!fromOpts.ok)
+        return fromOpts;
+    if (fromOpts.appId) {
+        return { ok: true, appId: fromOpts.appId };
+    }
+    const fromEnv = detectAppIdFromEnvWithErrorLogging();
+    if (!fromEnv.ok)
+        return fromEnv;
+    if (fromEnv.found) {
+        return { ok: true, appId: fromEnv.found.value };
+    }
+    return { ok: true };
+}
+async function handleQuery(queryArg, opts) {
+    const contextCount = (opts.admin ? 1 : 0) + (opts.asEmail ? 1 : 0) + (opts.asGuest ? 1 : 0);
+    if (contextCount === 0) {
+        error('Please specify a context: --admin, --as-email <email>, or --as-guest');
+        return process.exit(1);
+    }
+    if (contextCount > 1) {
+        error('Please specify exactly one context: --admin, --as-email <email>, or --as-guest');
+        return process.exit(1);
+    }
+    const { ok, appId } = await detectAppIdQuietly(opts);
+    if (!ok)
+        return process.exit(1);
+    if (!appId) {
+        error('No app ID detected. Please specify one with --app or set up with `instant-cli init`');
+        return process.exit(1);
+    }
+    let query;
+    try {
+        query = JSON5.parse(queryArg);
+    }
+    catch {
+        error('Invalid JSON query argument.');
+        return process.exit(1);
+    }
+    const headers = { 'app-id': appId };
+    if (opts.asEmail) {
+        headers['as-email'] = opts.asEmail;
+    }
+    else if (opts.asGuest) {
+        headers['as-guest'] = 'true';
+    }
+    const res = await fetchJson({
+        method: 'POST',
+        path: '/admin/query',
+        body: { query },
+        headers,
+        debugName: 'Query',
+        errorMessage: 'Failed to run query.',
+        command: 'query',
+    });
+    if (!res.ok)
+        return process.exit(1);
+    console.log(JSON.stringify(res.data, null, 2));
+}
 async function handlePush(bag, opts) {
     const pkgAndAuthInfo = await enforcePackageAndAuthInfoWithErrorLogging(opts);
     if (!pkgAndAuthInfo)
@@ -1494,9 +1566,10 @@ async function waitForAuthToken({ secret }) {
  * @param {boolean} [options.noLogError]
  * @param {string} [options.command] - The CLI command being executed (e.g., 'push', 'pull', 'login')
  * @param {string} [options.authToken] - Optional auth token to use instead of reading from config
+ * @param {Record<string, string>} [options.headers] - Extra headers to include in the request
  * @returns {Promise<{ ok: boolean; data: any }>}
  */
-async function fetchJson({ debugName, errorMessage, path, body, method, noAuth, noLogError, command, authToken: providedAuthToken, }) {
+async function fetchJson({ debugName, errorMessage, path, body, method, noAuth, noLogError, command, authToken: providedAuthToken, headers: extraHeaders, }) {
     const withAuth = !noAuth;
     const withErrorLogging = !noLogError;
     let authToken = null;
@@ -1517,6 +1590,7 @@ async function fetchJson({ debugName, errorMessage, path, body, method, noAuth,
                 'X-Instant-Source': 'instant-cli',
                 'X-Instant-Version': version,
                 ...(command ? { 'X-Instant-Command': command } : {}),
+                ...extraHeaders,
             },
             body: body ? JSON.stringify(body) : undefined,
             signal: AbortSignal.timeout(timeoutMs),