Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ dist/
/plans/
docs/superpowers/
.superpowers/
/data-app/starter/.altertable/
/data-app/starter/*
!/data-app/starter/bun.lock
/data-app/tests/test-results/
/data-app/tests/playwright-report/
4 changes: 2 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ Altertable CLI — a TypeScript/Bun command-line tool for querying and managing
| ---------------------- | --------------------------------------------------------- |
| `cli/src/` | CLI commands, HTTP clients, formatting, config |
| `cli/src/**/*.test.ts` | Colocated Bun unit tests for CLI logic |
| `data-app/starter/` | Runnable getting-started app copied by `app create` |
| `data-app/starter/` | Generated SDK fixture; only `bun.lock` is versioned |
| `data-app/tests/` | Browser tests and fixtures consuming the published package |
| `tests/` | Black-box end-user CLI tests run through `bin/altertable` |
| `specs/` | Client API specs (submodule — read-only from this repo) |
Expand All @@ -38,7 +38,7 @@ bun run --cwd data-app/starter build
bun run --cwd cli data-app:test:browser
```

The starter build requires its published package dependencies; see [data-app/README.md](data-app/README.md)
Setup generates the starter from `@altertable/data-app-examples` and installs its dependencies; see [data-app/README.md](data-app/README.md)
for setup and browser prerequisites. Run `bun run --cwd cli data-app:check` to check all
three data app projects together. Use `bun run check --quick` after focused checks,
then default `bun run check` before opening a PR.
Expand Down
2 changes: 1 addition & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

### Changed

- Generate, preview, and upgrade data apps with data-app 0.74.0.
- Generate, preview, and upgrade data apps with data-app 0.78.0. New projects use the editable standalone example and a shared `app.ts` declaration; directory and file previews verify its scope statically. Upgrades preserve existing source and identity; older `app.json` projects require an author-owned source migration.
- Raise the default `--connect-timeout` from 5 to 30 seconds, so queries that take a few seconds to start responding no longer time out.
- Timeout errors now name the CLI flag that fired, explain that the limit is client-side (the request may still be running on the server, and slow networks can cause it), and say how to raise it.

Expand Down
4 changes: 2 additions & 2 deletions COMMANDS.md
Original file line number Diff line number Diff line change
Expand Up @@ -422,7 +422,7 @@ altertable app create|dev|build|lint|upgrade|validate|publish|update

**Subcommands**

- `create` — Create a local data app project with a live connection check.
- `create` — Create a local data app project from the editable standalone example.
- `dev` — Preview a local data app directory, or a single-file data app, with lakehouse access.
- `build` — Typecheck and build a local data app without Altertable credentials.
- `lint` — Lint a local data app project: format, lint rules, types, contracts, build, and client credential boundary.
Expand All @@ -447,7 +447,7 @@ altertable app update APP-1 --file index.tsx

#### `altertable app create`

Create a local data app project with a live connection check.
Create a local data app project from the editable standalone example.

**Usage**

Expand Down
5 changes: 3 additions & 2 deletions DEVELOPMENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,8 @@ bun run check:package # focused build, pack, and extracted-consumer smok
```

The root is a private command entry point, not a workspace: `cli/bun.lock` and the
starter and browser-test lockfiles remain independent. Individual commands above
starter and browser-test lockfiles remain independent. Setup generates the starter from the
pinned `@altertable/data-app-examples` package; only its frozen lockfile is versioned here. Individual commands above
operate on the CLI; the canonical check also covers top-level tests and the data app
consumers. Install dependencies explicitly with `bun run setup` before checking;
verification does not install development dependencies. Artifact smoke tests still
Expand Down Expand Up @@ -285,4 +286,4 @@ When bumping the `specs/` submodule, extend the mapped tests before merge.

## Data apps

The runnable starter and package-consumer browser tests live in [`data-app/`](data-app/README.md). That guide covers starter embedding, npm package pins, package upgrades, and verification. Runtime development and releases belong to [the Data App repository](https://github.com/altertable-ai/data-app).
The generated SDK starter fixture and package-consumer browser tests live in [`data-app/`](data-app/README.md). That guide covers starter embedding, npm package pins, package upgrades, and verification. Runtime development and releases belong to [the Data App repository](https://github.com/altertable-ai/data-app).
2 changes: 1 addition & 1 deletion cli-reference.json
Original file line number Diff line number Diff line change
Expand Up @@ -835,7 +835,7 @@
{
"id": "altertable-app-create",
"command": "altertable app create",
"description": "Create a local data app project with a live connection check.",
"description": "Create a local data app project from the editable standalone example.",
"usage": [
"altertable app create [options] <NAME>"
],
Expand Down
2 changes: 1 addition & 1 deletion cli/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ bun test "$PWD"/tests/integration.e2e.ts

## Conventions

- For generated app authoring, edit [the starter app guide](../data-app/starter/AGENTS.md). Keep it a task router into focused authoring guides and the installed package docs. Types describe props; reserve JSDoc for constraints, ownership, security boundaries, and surprising behavior.
- The generated starter and its authoring guides come from the pinned `@altertable/data-app-examples` package. Change examples in the SDK repository; this CLI owns distribution, identity injection, the frozen lockfile, and integration tests. See [data app integration](../data-app/README.md).
- Runtime contracts and UI components are maintained in [the Data App repository](https://github.com/altertable-ai/data-app). This repository owns the starter and its integration with CLI commands.

- Declare and export each command immediately after its imports; keep supporting helpers and types below it.
Expand Down
8 changes: 8 additions & 0 deletions cli/bun.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

3 changes: 3 additions & 0 deletions cli/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,7 @@
"pack:check": "bun run build && bun run scripts/check-package.ts",
"knip": "knip --no-config-hints",
"knip:production": "knip --production --no-config-hints",
"data-app:prepare": "bun run scripts/prepare-data-app.ts",
"data-app:check": "bun run scripts/check-data-app.ts",
"data-app:test:browser": "cd ../data-app/tests && bun run test",
"test:watch": "bun test --watch"
Expand All @@ -54,6 +55,8 @@
"yaml": "2.9.0"
},
"devDependencies": {
"@altertable/data-app-examples": "0.78.0",
"@altertable/data-app-manifest": "0.78.0",
"@types/bun": "1.4.3",
"eslint-plugin-no-relative-import-paths": "1.6.1",
"knip": "6.32.2",
Expand Down
46 changes: 31 additions & 15 deletions cli/scripts/check-data-app.ts
Original file line number Diff line number Diff line change
@@ -1,19 +1,35 @@
import { join } from 'node:path';
import { cp, mkdtemp, rm, symlink } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { basename, join } from 'node:path';

import { dataAppDirectory } from '@/commands/app/lib/distribution.ts';
import { dataAppDirectory } from '@/commands/app/lib/distribution-source.ts';

for (const project of ['starter', 'tests']) {
const commands = [
...['typecheck', 'lint', 'format:check'].map(name => ['run', name]),
...(project === 'starter' ? [['run', 'build']] : []),
];
for (const args of commands) {
const child = Bun.spawn([process.execPath, ...args], {
cwd: join(dataAppDirectory, project),
stdout: 'inherit',
stderr: 'inherit',
});
if (await child.exited)
throw new Error(`${project}: bun ${args.join(' ')} failed`);
// Check outside the checkout so formatters inspect the Git-ignored generated source too.
const fixture = await mkdtemp(join(tmpdir(), 'data-app-check-'));
try {
const starter = join(dataAppDirectory, 'starter');
await cp(starter, fixture, {
recursive: true,
filter: path =>
!['node_modules', 'dist', '.altertable'].includes(basename(path)) &&
!basename(path).startsWith('.env'),
});
await symlink(join(starter, 'node_modules'), join(fixture, 'node_modules'));
for (const project of [fixture, join(dataAppDirectory, 'tests')]) {
const commands = [
...['typecheck', 'lint', 'format:check'].map(name => ['run', name]),
...(project === fixture ? [['run', 'build']] : []),
];
for (const args of commands) {
const child = Bun.spawn([process.execPath, ...args], {
cwd: project,
stdout: 'inherit',
stderr: 'inherit',
});
if (await child.exited)
throw new Error(`${project}: bun ${args.join(' ')} failed`);
}
}
} finally {
await rm(fixture, { recursive: true, force: true });
}
4 changes: 2 additions & 2 deletions cli/scripts/package-data-app.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
import type { BunPlugin } from 'bun';

import { readDataAppPayload } from '@/commands/app/lib/distribution.ts';
import { readDataAppPayload } from '@/commands/app/lib/distribution-source.ts';

/** Both npm and native releases embed the same deterministic project templates. */
export function dataAppPlugin(): BunPlugin {
Expand All @@ -10,7 +10,7 @@ export function dataAppPlugin(): BunPlugin {
build.onLoad(
{ filter: /[/\\]commands[/\\]app[/\\]lib[/\\]payload\.ts$/ },
async () => ({
contents: `export const dataAppPayload = ${JSON.stringify(await readDataAppPayload())};`,
contents: `const dataAppPayload = ${JSON.stringify(await readDataAppPayload())}; export function loadDataAppPayload() { return Promise.resolve(dataAppPayload); }`,
loader: 'js',
})
);
Expand Down
25 changes: 25 additions & 0 deletions cli/scripts/prepare-data-app.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
import { mkdir, readdir, rm, writeFile } from 'node:fs/promises';
import { dirname, join } from 'node:path';

import {
dataAppDirectory,
readDataAppPayload,
} from '@/commands/app/lib/distribution-source.ts';
import { createAppFiles } from '@/commands/app/lib/distribution.ts';

// This disposable project is the same scaffold shipped in the CLI, not another source template.
const files = createAppFiles(await readDataAppPayload(), {
name: 'data-app-starter',
title: 'CLI scaffold test',
scope: { organization: 'Acme', environment: 'production' },
});
const directory = join(dataAppDirectory, 'starter');
for (const name of await readdir(directory)) {
if (name === 'bun.lock' || name === 'node_modules' || name.startsWith('.env'))
continue;
await rm(join(directory, name), { recursive: true, force: true });
}
for (const [name, content] of Object.entries(files)) {
await mkdir(dirname(join(directory, name)), { recursive: true });
await writeFile(join(directory, name), content);
}
25 changes: 17 additions & 8 deletions cli/scripts/smoke-data-app.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,15 @@ import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';

import { recommendedDataAppVersion } from '@/commands/app/lib/package.ts';
import { loadDataAppPayload } from '@/commands/app/lib/payload.ts';

/** Exercise the shipped CLI outside the checkout, including its embedded starter and published runtime. */
export async function smokeDataApp(
command: string[],
scaffoldOnly = false
): Promise<void> {
const version = recommendedDataAppVersion(await loadDataAppPayload());
const directory = await mkdtemp(join(tmpdir(), 'altertable-packaged-app-'));
const app = join(directory, 'app');
let upstream: Bun.Server<undefined> | undefined;
Expand Down Expand Up @@ -105,13 +109,15 @@ export async function smokeDataApp(
throw new Error('File preview did not bundle the app.');
}
const query = await fetch(
`${url}${singleFile ? '/api/sql' : '/api/data/connection'}`,
`${url}${singleFile ? '/api/query' : '/api/query/totalCost'}`,
{
signal: AbortSignal.timeout(5000),
method: 'POST',
headers: { origin: url, 'content-type': 'application/json' },
body: JSON.stringify(
singleFile ? { statement: 'select 1', limit: 1, params: {} } : {}
singleFile
? { queryId: 'connection', limit: 1, params: {} }
: { limit: 1, params: { month: '2026-09', customerName: '' } }
),
}
);
Expand All @@ -120,7 +126,7 @@ export async function smokeDataApp(
rows?: unknown[][];
data?: unknown;
};
if (singleFile ? result.rows?.[0]?.[0] !== 1 : result.data !== true)
if (result.rows?.[0]?.[0] !== (singleFile ? 1 : 1320000))
throw new Error('Preview did not return the lakehouse query result.');
} catch (error) {
failure = error;
Expand Down Expand Up @@ -170,7 +176,7 @@ export async function smokeDataApp(
'@altertable/data-app-react',
'@altertable/data-app-bun',
]) {
if (manifest.dependencies?.[name] !== '0.74.0')
if (manifest.dependencies?.[name] !== version)
throw new Error(
`Packaged starter must pin ${name} to the tested release`
);
Expand All @@ -188,14 +194,17 @@ export async function smokeDataApp(
upstream = Bun.serve({
hostname: '127.0.0.1',
port: 0,
fetch(request) {
async fetch(request) {
if (
request.headers.get('authorization') !==
`Basic ${Buffer.from('preview-user:preview-smoke-secret').toString('base64')}`
)
return new Response('Unauthorized', { status: 401 });
const { statement } = (await request.json()) as { statement: string };
return new Response(
'{"query_id":"smoke"}\n[{"name":"connection_check","type":"INTEGER"}]\n[1]',
statement === 'SELECT 1 AS connection_check'
? '{"query_id":"smoke"}\n[{"name":"connection_check","type":"INTEGER"}]\n[1]'
: '{"query_id":"smoke"}\n[{"name":"cost_cents","type":"BIGINT"},{"name":"customer_count","type":"BIGINT"}]\n[1320000,3]',
{
headers: { 'content-type': 'application/x-ndjson' },
}
Expand All @@ -215,7 +224,7 @@ export async function smokeDataApp(
[
process.execPath,
'-e',
'import { createDataHandler } from "@altertable/data-app/server"; import { localLakehouse } from "@altertable/data-app-bun"; if (typeof createDataHandler !== "function" || typeof localLakehouse !== "function") process.exit(1);',
'import { createDataClient } from "@altertable/data-app/client"; import { serveLocalApp } from "@altertable/data-app-bun"; if (typeof createDataClient !== "function" || typeof serveLocalApp !== "function") process.exit(1);',
],
app
);
Expand All @@ -225,7 +234,7 @@ export async function smokeDataApp(
join(app, 'index.tsx'),
`import { defineDataApp as declareApp } from "@altertable/data-app";
import { mountDataApp } from "@altertable/data-app-react";
const app = declareApp({ title: "File preview smoke", description: "Smoke test", scope: { organization: "Test", environment: "test" }, queries: {} });
const app = declareApp({ title: "File preview smoke", description: "Smoke test", scope: { organization: "Test", environment: "test" }, queries: { connection: { statement: "SELECT 1 AS connection_check", params: {}, projections: { connection_check: { type: "number" } } } } });
function View() { return <p>File preview smoke</p>; }
mountDataApp({ app, component: View });`
);
Expand Down
Loading
Loading