feat(cli): introduce local data apps - #118
Merged
Merged
Conversation
Share in-flight credential provisioning, refresh near expiry, and retry one recoverable unauthorized response so local app previews can continue querying without a restart.
Add create, dev, check, build, and guarded upgrade commands with a versioned React runtime template. Include generated command references and the template formatting gate. The branch now contains the reusable starter without the trial app directories from development.
Keep repository routing guidance with the CLI, and point generated app authors to the runtime contract and validation workflow.
redox
reviewed
Sep 28, 2026
Member
There was a problem hiding this comment.
all those .txt appear to me a pain to maintain and test etc...
Member
There was a problem hiding this comment.
@francoischalifour now I wonder if it wouldn't be simpler to have a data-apps-template repostitory with have this CLI clone/download it.
Member
Author
There was a problem hiding this comment.
For now it's super convenient to have the templates in the app because the agent has no issues updating them from the instructions you give on a generated app. This works automatically thanks to app dev --watch-runtime. Extracting this now will slow down the feedback loop.
Use the ALTER keypad port for new app previews and report a clear error when it is occupied. Keep --port as the explicit override for concurrent apps.
Run app-owned appearance, operation, and optional lakehouse checks in a fresh Bun subprocess. This keeps computed imports of generated project files out of the standalone CLI module graph, so hardened release builds retain --reject-unresolved while app check works from compiled binaries.
albert20260301
approved these changes
Sep 28, 2026
Make generated apps describe each exploration through a typed description, scope, limitations, and glossary. Keep presentation steps app-owned in App.tsx and pass the same context into step inspection so Present mode retains its explanations and query links. This changes the generated runtime UI contract and bumps its version to 0.56.0. Existing prototype apps using Methodology or MeasureExplanation need to migrate before app upgrade.
Expose a numeric count on TableCard and DataPanel so app titles stay concise. Render exact counts in a smaller muted style, including zero, and update the starter to pass its table count separately.
Keep the exploration description in the About the data header and retain only Glossary and Queries tabs. Simplify the generated data context and Present step contract to glossary and query references, so the removed Scope, Limitations, and per-step provenance fields cannot reappear through the runtime API.
Seed a data app from a configured organization and environment by default. Keep --without-profile as an explicit offline path, and guide users to login when their profile is incomplete.
Display the group usage for commands such as altertable app when invoked without a subcommand. Preserve structured help in JSON mode so scriptable invocations also return guidance.
Replace the bounded table sample and sample Present story with a lightweight SQL connection check. Show checking, verified, and failure states from the query result, followed by concrete authoring steps. Keep the runtime Present capability available for apps with an authored story.
Use a fixed 12px count label beside data panel titles so its visual weight stays consistent with other panel metadata.
Move data app templates into canonical TypeScript projects so runtime behavior and the getting-started app can be checked directly. Declare copied files through starter and package allowlists, and embed one deterministic payload into npm and native releases. Preserve public runtime imports and migrate managed files through app upgrade. Refresh dependency locks transactionally, validate peer compatibility, and restore runtime, manifest, and lockfile on failure. Keep application-owned source intact. Extract runtime tests, add desktop and phone browser coverage including Present mode, and smoke-test standalone apps from both release artifacts. Replace the starter theme selector with its existing single-button toggle.
albert20260301
approved these changes
Sep 28, 2026
Provide a standard page shell, query-backed starter, integrated request states, browser and local server entry points, and reusable input/result parsers. Preserve authored SQL and exploration context in the app. Add runtime contract tests and bump the private runtime version for app upgrades.
Use runtime-owned connection UI, page setup, browser/server entry points, and request-state composition in the runnable starter. Move starter styling into the runtime, update generated authoring guidance, and verify retry, stale data, theme, context, and Present behavior in browser fixtures.
Provide a standard page shell, query-backed starter, integrated request states, browser and local server entry points, and reusable input/result parsers. Preserve authored SQL and exploration context in the app. Add runtime contract tests and bump the private runtime version for app upgrades.
Use runtime-owned connection UI, page setup, browser/server entry points, and request-state composition in the runnable starter. Move starter styling into the runtime, update generated authoring guidance, and verify retry, stale data, theme, context, and Present behavior in browser fixtures.
Group UI components and their styles into app, layout, cards, requests, controls, inspect, presentation, and primitives. Preserve existing package imports and public exports while making implementations easier to locate. Ship an API map with the vendored runtime and document why generated apps commit that dependency. Verify source projects, all public UI exports, and generated-app creation and upgrades.
Ship focused data and view authoring guides behind a concise AGENTS.md router. Document the public runtime API map and why generated apps track the vendored runtime. Remove redundant JSDoc while retaining constraints and surprising behavior. Verify shipped Markdown links and runtime Git ownership; comment edits preserve emitted code.
Keep components and their styles directly under src/ui so authors can find them by name. Retain task-based discovery in the runtime API map and update imports, package exports, and distribution assertions.
Keep operation fixtures and exploration context aligned when replacing the connection starter. Let agents use existing MCP or CLI access without an unnecessary connection prompt. Route shared guidance through AGENTS.md and keep operation and view rules in their focused guides.
redox
approved these changes
Sep 28, 2026
Build a local data app from production product analytics events for a fixed 31-day window. Compare tracked feature actions and identities outside the Altertable workspace, explain scope and overlap, and retain a dated source-backed snapshot if live access fails.
# Conflicts: # data-app/README.md # data-app/runtime/package.json # data-app/runtime/src/config.ts # data-app/runtime/src/contract.ts # data-app/runtime/src/react.tsx # data-app/runtime/src/ui/AppHeader.tsx # data-app/runtime/src/ui/AppToolbar.tsx # data-app/runtime/src/ui/ContentSkeleton.tsx # data-app/runtime/src/ui/DataApp.tsx # data-app/runtime/src/ui/GettingStarted.tsx # data-app/runtime/src/ui/Grid.tsx # data-app/runtime/src/ui/PeriodSummary.tsx # data-app/runtime/src/ui/Stack.tsx # data-app/runtime/src/ui/index.ts # data-app/starter/AGENTS.md # data-app/starter/README.md # data-app/starter/fixtures/main.tsx # data-app/tests/starter.spec.ts
Give DataApp ownership of primary request states, refresh feedback, and inspection defaults without adding a reporting-period subtitle. Share date-range parsing with URL controls and stale-result descriptions, and keep bounded live-check inputs beside each operation instead of duplicating them in app.json. Add typed evidence references, metric formatting, stable category colors, table search ownership, and card skeletons. Keep starter agent guidance focused on data investigation and editorial judgment, with browser coverage for the resulting behavior.
Contributor
|
Opened #119 against this branch to fix the type-aware lint failure in the data-app contract test. It preserves the awaited rejection check and is limited to test code. |
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
Contributor
|
Reviewed the CodeQL finding: the regex is confined to a test assertion over fixed JSX rendered with renderToStaticMarkup; it is not used to sanitize or render untrusted production input. There is no application HTML-injection sink on this path. This account lacks permission to dismiss code-scanning alerts, so recording it as a test-only false positive. |
This was referenced Sep 29, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Context
The CLI can query Altertable data, but building an interactive app from those results has required authors to assemble data access, UI state, visualizations, and validation themselves. This branch provides a local workflow with a clear ownership boundary: app authors define questions, operations, data context, and views in
src/, while the generated runtime supplies transport and reusable UI contracts.What changed
altertable app create,dev,check,build, andupgrade.AGENTS.md.app dev --watch-runtimeupgrades an unmodified runtime and restarts the preview; it stops with a conflict when generated files have been edited.app checkvalidate format, lint, types, operation contracts, the build, and client assets for credential references.--lakehousealso runs the declared operations against the selected lakehouse.Usage
With an organization and environment configured in the selected CLI profile:
altertable app create product-pulse cd product-pulse altertable app devDevelop the first useful view in
src/, then validate and build it:altertable app check altertable app check --lakehouse altertable app buildAfter updating the CLI, refresh an unmodified generated runtime with
altertable app upgrade. Runtime contributors can usealtertable app dev --watch-runtimeto apply template changes and restart the preview automatically.Architecture
flowchart LR Browser["Browser UI"] --> Route["App same-origin API route"] Route --> Proxy["CLI local query proxy"] Proxy --> Lakehouse["Selected Altertable lakehouse"] Author["App-owned src/"] --> Browser Author --> Route Runtime["Generated .altertable/runtime/"] --> Browser Runtime --> Route CLI["CLI profile and credentials"] --> ProxyThe app owns its questions, operations, data context, and view. The runtime owns shared UI and request behavior. Credentials remain on the server side.
Validation and upgrade flow
flowchart LR Create["app create"] --> Develop["Edit app-owned src/"] Develop --> Check["app check"] Check --> Build["app build"] Templates["Runtime template changes"] --> Guard["Integrity check"] Guard -->|Unmodified| Upgrade["Upgrade runtime and restart preview"] Guard -->|Edited generated file| Conflict["Stop with file conflict"]This branch covers local creation, preview, validation, and build. Hosted deployment and share authorization are outside its scope.
Related