evidence-dev / evidence-vscode Goto Github PK

and display running process id to help troubleshoot all executed terminal command sequences.

to view running Evidence app status, and start or stop app dev server via terminal commands from #4.

• Use VSCode Status Bar Item API to create custom Evidence app status indicators. See statusbar-sample extension for example. Follow Status Bar UX Guildelines
• Add Start, Stop and Running dev server status display with the corresponding commands

in addition to the Evidence: Open Settings File from #5 to enable configuring data source(s) via Evidence app UI.

• Use Simple Browser Preview from #3 to display Evidence app settings in a browser in VSCode IDE
• Start Evidence dev server, if not running, to show settings page

• Create utils/jsonUtils.ts to load package.json from the open project workspace
• Add hasDependency() to the new jsonUtils.ts to check for any dev and regular node.js dependencies
• Use new jsonUtils in extension activation method to enable Start Dev Server command, etc.

We researched this yesterday and shared preliminary info in slack:

looking at the built-in simple browser implementation I don't see a quick and easy way for us to open it on the side, or change that webview title and icon. So, if we want to see more stylized Evidence built-in browser and have more open/close/reload page options, we'd need to invest time into implementing our own. ... https://github.com/microsoft/vscode/blob/main/extensions/simple-browser/src/extension.ts

Also, that Simple Browser webview API doesn't provide close view option, and VS Code itself still doesn't have an API to iterate over all open webviews, only visibleTextEditors list is available. Therefore, it is not possible for us to close Simple Browser, without implementing our own or using another extension like the popular, but not maintained Browser Lite.

The only other quick workaround without investing 2-3 days on implementing your own custom Evidence App webview, is:

• Have your app dev team add Start Dev Server "greeting" page to your app ./static folder and standard app template
• We can set global state for when we open one of the Evidence pages in a Simple Browser extension, and what page it was on
• On VS Code reload and Evidence extension activation, we can show new Start Dev Server "greeting" page in a Simple Browser, so that it doesn't show up blank.
• When a user starts a server, we can take them to the last viewed page saved in the global state from the previous Preview session.
• and lastly, your app still needs proper Loading ... home page while the server starts and generates pages. I've requested this multiple times in slack and tickets here to address long blank app page view in a browser.

That's a few hours, most likely a day of setup, dev, testing and coordination with the app dev team, if you'd like us to open a UX enhancement ticket to address it this or next week.

On the related note, we can also open new active editor group on the side, and maybe add Preview on the Side for the Simple Browser to show up there. However, changing that built-in browser title and icon is not possible per my read of that built-in vscode extension API referenced above.

Originally posted by @RandomFractals in #24 (comment)

We should do this to prevent Evidence commands display in Command Palette, file explorer and editor context menus for the open project workspaces with .md and package.json files that are not Evidence web app projects.

See info logging in #28 and template creation logging in #2.

• Refactor and consolidate extension info logging in one place

• Add new Limitations section to docs with info about no support:
  • for nested Evidence project folders (#25 (comment))
  • missing standard and Evidence markdown document Outline display (#33)
  • no busy port detection (#31)
  • not supported Proview of templated pages (#30)

with instructions how to build this VS Code extension project for Evidence dev team and others from the dev community to check out the latest version before new release.

We'll use this example: https://github.com/RandomFractals/vscode-data-table#dev-build

• Add Evidence: Preview command with evidence.preview id
• Use VSCode Terminal API to start evidence app server instance
• Create custom Evidence Preview Webview with URL input field, back/forward nav buttons, and a link to open app in a browser.
• Use built-in VSCode Simple Browser extension to display app content or implement our own
• Ensure only one app Preview can be open at the time
• Automatically open local Evidence app in a Simple Browser after starting local app dev server
• Rewrite and map Evidence .md filenames using app routes to display Preview for the open .md document/page. See file based routing doc for more info.
• Add VSCode file explorer and editor title context menus to open app Preview for the emd documents in a project.
• Start Evidence server, if not running, to show the requested markdown document Preview
• Ensure Evidence app Preview supports custom components rendering

This is not really a discrete feature vs a place to discuss this in public.

Taking inspiration from the Malloy codespace which is excellent.

Some notes from @hughess

Was checking out Malloy’s extension again:
They have a really smooth getting started path - maybe we should replicate

• Theirs is click to “try Malloy in your browser now”
• That opens a github.dev link, which takes you to codespace
• Codespace is working right away, clicking to run a query brings up almost instant feedback

Would be great to get to an "everything just works" experience in Evidence template codespace. If we need to make changes to the template to support this, we can

Fine tuning -- not for current release

If you launch the dev server while localhost:3000 is occupied elsewhere, evidence will launch on localhost:3001 -- the simple browser preview that the extension opens should respect the new development url.

• Run npm install via terminal from #4 to install NodeJS modules for the Evidence project.
• Stop a running dev server to run node packages update

Aware that this is a "next week" (rather than right now) task but wanted somewhere to write about this.

Feel free to break down into smaller issues and close this one if it makes sense.

Draft Acceptance Criteria (to be refined)

• User can run SQL file queries in VSCode and get results into some kind of visual output
• Works for any supported database adapter
• Works for chained queries
• (Optional) User can run inline queries in VSCode. Results are returned in table ?below the markdown fence in the code
• (Optional) User gets autocomplete for their database. @RandomFractals I think you suggested we might be able to rely on another extension for this. If this is hard / time consuming then deprioritize.
• (Very optional) User can see tables, schemas etc in their database in some kind of sidebar. I have no idea how hard this is, and may want to deal with separately, possibly in the future.

Other thoughts

• We should try to sensibly handle if a user tries to select * from table and return 100,000 rows to VSCode. Should we break, return error, paginate

per comments in #32

• Update those command titles in package.json
• Update Commands section in 'README.md`
• Update commands pic in docs/images

Just want to leave this as a flag for us in the future, no action required.

This is totally fine for now, but eventually it seems like we should be respecting whatever version semver users have in their project (e.g. they are only accepting minor bumps).

• To initialize Evidence template project after it is cloned in #2
• To resolve current template app needful_things.duckdb data source config issues
• And to start a new project created from a template project without any errors or additional manual configuration/settings required

Related ticket with more info on that configuration: evidence-dev/evidence#885 (comment)

We'll resolve this on our end by:

• Adding the required templateProjectSettings json config to commands/template.ts implementation
• Creating .evidence/template/evidence.settings.json file after a project is scaffolded from the github template project repo
• And adding the required demo DuckdDB config to that file for the new project created from a template to start and run without any missing data or query errors

.evidence/template/evidence.settings.json:

{
  "database": "duckdb",
  "credentials": {
    "filename": "needful_things.duckdb",
    "gitignoreDuckdb": null
  }
}

• We'll also refine all the Create Project from Template info messages, prompts and progress display UI parts for a better project starter navigation/creation UX flow

To Replicate

1. Create Evidence project from Template
2. Hit nice new play button in the bottom bar

Expected Behaviour

Browser page loads with Evidence project rendered

Actual Behavior

Browser page stays blank.
If you hit browser refresh button then loads as expected

• List steps to create new project from a template
• Add Create Project from a Template demo gif
• Update changelog with this ticket info for the v1.0.0 release

to delete cached content from .evidence/template/.evidence-queries folder.

Evidence queries folder stores results from SQL queries that pull data from the configured data source(s) and are linked and displayed in the app pages/views. See Query Cache in Evidence dev docs for more info.

• Display notification message when cached data is cleared, or the queries data folder doesn't exist.

Evidence.dev has a published VSCode extension with emd language grammar, configuration and code snippets.

We'll import existing Evidence extension code from the Evidence monorepo, and will use it as a starting point for the Evidence extension with Preview and other new interactive features.

Per our discussions and scope set for the phase 1 of interactive Evidence extension features, we'll add Evidence: New Project functionality.

UX and Flow Details

• Add new evidence.newProject command config to package.json
• Add New Evidence Project context menu to folders in the File Explorer by adding evidence.newProject command to menus: explorer:context [] commands and contribution point in extension package.json config
• Add NewEvidence enum value to Commands to register enum in commands.ts
• Create new src/commands/project.ts for the project command(s) implementation with Select Folder dialog when no new project folder Uri is provided
• Display Open Dialog for the folder selection when this command is called from the Command Palette...
• Display an Info message if the selected folder contains files, and prompt to create and use new empty workspace folder for the new Evidence project
• Extend current project from template functionality from #2 to create New Evidence Project inside the selected folder in VS Code File Explorer
• Clone Evidence template project to the selected empty workspace folder
• Open new Evidence project folder in a new VS Code window.

• Add new Commands section to readme.md with the commands md table and descriptions.

Example: https://github.com/RandomFractals/tabular-data-viewer#commands

VSCode provides public API and configuration options available to all extensions to create interactive Walkthroughs and onboard new users via a guided tour of features.

We'll use walkthroughs to highlight the initial set of new interactive Evidence extension features.

Proposed content and walkthrough steps we can include in the first interactive Evidence ext. v1.0.0 release:

• Brief Welcome to Evidence BI app building message
• NodeJS version check and prompt to install
• Create new Evidence project using #2
• Start Evidence app server using #4
• Preview running Evidence app (#3)

We'll use walkthroughs config documentation for this implementation.

• Use Terminal API to implement integration of evidence app and extension with the Terminal interface in VSCode
• Set terminal title to Evidence
• Provide commands to start and stop Evidence app server
• Check and install NodeJS dependencies prior to starting app dev server
• Display NodeJS version via node -v command when initializing terminal
• Update Evidence app server status and status bar UI options
• Use this terminal interface to install Evidence app and UI component dependencies
• Use new terminal API to bootstrap Evidence app Preview in #3

Evidence app CLI commands: https://docs.evidence.dev/cli/

CLI impl.: evidence/cli.js

to scaffold new Evidence app project.

• Use Evidence Template Project source code as a template
• Create an API that would take any github repository url to create new Evidence project from a template or a demo app
• Prompt to create new empty project folder for new Evidence app from template
• Use tiged JS API to clone template/demo project source code from github
• Delete degit.json and .github folder with smoke test workflows after template project cloning
• Review and reuse what's possible from the current build-template.js code in evidence core package.

Note: there is a new open issue in the core Evidence repo to move template project into that monorepo (evidence-dev/evidence#883). Our recommendation would be to keep template project, current and future demo apps in separate repositories to make it easier for your end-users to clone, build, and use them.

to build the static version of Evidence app/reports as described in Evidence Build Commands documentation section.

• Add Evidence: Build command
• Add Evidence: Build Strict command for the strict mode
• Check for /node_modules folder and install dependencies via #13 prior to running build commands
• Stop running Evidence dev server prior to executing build commands

per initial internal review of the v1.0.0 of this extension and finding that the current extensive list of commands is long and might be somewhat overwhelming to the Evidence app users using VS Code. See #34 fore more info.

• Set evidence.viewSettings command to never in commandPalette menu contribution point in package.json extension manifest.
• Update Commands section and pic in docs for the v1.1.0 release with this and other UI enhancements (#35 & #36)

Really cool overall, I could see myself using it for sure.

Nits and bugs

• Start server -- I see a blank simple browser while the project boots, but it never seems to clear for me. I have to hit reload to get it up.
• Start server, and the preview command do the same thing. I think for clarity we should only offer one command. My preference would be "start dev server". If there's a convention for "preview" that's ok too, but just one. Change should also be reflected in the tooltip for the button in the status bar.
• I think commands which kill the dev server (stop server, update, install etc.) should shut the simple browser preview window. Today it stays visible, but the app is in a broken state when the dev server is shut down, and it won't respond to updates in markdown.
• After initializing from the template, or re-opening vscode, I don't see the start dev server shortcut in the status bar until I have actually opened a .md file. I think the command should be visible in the status bar at all times when you are in a workspace which contains an Evidence project.

Gifs

We can use the start server demo gif from #3 (comment) for now.

• Cut a better Evidence app run extension demo gif
• Add it to the intro section in readme.md

Looking good. I like it a lot!

Some final QA from me.

Port handling

EDIT: see #31

If port 3000 is busy in another process, then vite uses 3001 (i was writing docs for evidence on another port).

However the VSCode extension always uses 3000.

Can we detect which port it opens and open the browser on that one?

Commands

We have quite a lot of commands which can add a level of mental load to the user when choosing the right one. I think we might be able to reduce the number slightly

There are a couple of commands that feel a bit duplicative to me, so we might want to consider dropping them:

Settings

• View settings vs Open settings file
  • I understand these are different, but do we need VSCode shortcuts from them both?
  • I would probably remove the view settings one as there is a big button in the UI, though I am happy to hear the case if others disagree

Dev server

• Preview vs Start Server
  • As an end user I don't really understand the difference here. They both boot the server up
  • Consider removing preview
    • (side note) In my mind, preview is what you do post build, if you want to drive around the built artifacts

to gauge the number of users updating Evidence VS Code extension in the upcoming releases.

• Use shields.io API and service for those badges

Sample display of those VS Code extension badges from our Geo Data Viewer:

Evidence extension maps keybindings for the built-in markdown document Preview commands in package.json. This hides access to the .md Preview for the standard markdown documents.

https://github.com/evidence-dev/vscode/blob/main/package.json#L109

keybindings": [
      {
        "command": "markdown.showPreview",
        "key": "shift+ctrl+v",
        "mac": "shift+cmd+v",
        "when": "!notebookEditorFocused && editorLangId == 'emd'"
      },
      {
        "command": "markdown.showPreviewToSide",
        "key": "ctrl+k v",
        "mac": "cmd+k v",
        "when": "!notebookEditorFocused && editorLangId == 'emd'"
      }
    ]

Current emd language configuration also marks all .md files as Evidence markdown documents.

We need to resolve this issue to avoid negative reviews in vscode marketplace. Evidence markdown should not hijack normal .md handling in vscode.

Recommended solution used by all custom markdown language flavors in vscode is to use a custom filename extension (.emd) for the Evidence app page files.

See related thread in vscode channel in Evidence dev slack.

to resolve general confusion about App Preview and Start Server commands, encountered during initial internal testing of v1.0.0. See initial review and test results feedback in #24 and #34 for more info.

• Add menus/commandPalette contribution point to package.json and set evidence.preview command to never show there
• Update Commands pic in docs/images before releasing this feature in v1.1.0

I might have the wrong mental model about vs code extensions, but after playing with this, I wonder if this might be a reasonable way forward on a couple items.

I think we should have the extension detect whether or not there is an Evidence project in the current VS code workspace, and use that information to determine which status bar items, or command palette items are available.

If it's possible to use that same approach to decide how to treat .md files, I also think that would be a sensible way to go.

Detecting an Evidence project

• For the foreseeable future, any package.json which includes an "@evidence-dev/evidence" dependency could be safely assumed to be in the root of an evidence project
• Monorepos
• Users co-locate their evidence projects in monorepos. It won't be safe to assume that the above package.json will be in the root of workspace.
• If we find the project root in another directory, all of the status bar / command palette commands should be run with their working directory set to the root of the evidence project, whether it's the root of the workspace or not.

Treatment of status bar items / commands

When an evidence project is detected in the workspace, we should offer all of the commands and status bar items, regardless of what files are open in vscode.

Eventually we might have some commands which are file specific, but right now all of them are project-level.

Treatment of markdown files

It seems like we're facing some weird trade-offs to have the extension whether or not we can safely override the built in markdown features

The options so far are:

• Create a new file extension, e.g .emd
• Add some flags to frontmatter
• Write some sort of detection logic to parse markdown and judge
• ?

If it's possible to use logic beyond just the file extension to determine how to treat the file, I think we could use the above approach to make a simpler judgements about how to treat the .md files that the extension encounters:

1. All .md files inside project-root/pages can safely be treated as evidence markdown
2. All .md files outside of project-root/pages should be treated as regular markdown

For example, the readme.md in the root of an evidence project should not be treated like evidence markdown.

to updated evidence libraries to the latest version.

• Use npm install @evidence-dev/evidence@latest, etc. terminal commands to implement this shortcut.
• Stop a running Evidence dev server prior to libraries update

• Bump this extension version to 1.0.0 and use major/minor versioning thereafter
• Add Evidence Commands and extension demo gif to readme.md
• Update changelog.md with new features and tickets info from this new ext. repo
• Update extension features list in docs
• Change Issues link in docs to point to this repository issues
• Change git url and issues link in package.json to point to this repository
• Add Evidence ext. keywords to this repository tags to make it discoverable on github
• Add brief v1.0.0 release intro to the changelog.md
• Rename this VS Code extension repository to evidence-vscode and update repository references in package.json
• Make this repository public for v1.0.0 release (@mcrascal)
• Change demo and commands images to use absolute url for display in VS Code marketplace after this repository is made public (@RandomFractals)
• Tag evidence-vscode-v1.0.0 release and create release notes with .vsix attachment (@RandomFractals)

Blocked by evidence-dev/evidence#901

Fine tuning -- not for the current release.

Previewing a page that has parameters in the route is counter intuitive -- the extension injects [name_of_parameter] into the url and opens that page.

Given the information that's available to the extension, I think it will be quite difficult to correctly navigate to a parameterized route.

If it's not possible to find these routes, I think it'd be preferable to simply not offer "right click to preview", or the editor action preview button on any markdown that is in a parameterized route.

If it's not possible to distinguish these routes, I would remove right click to preview, and the preview editor action for all evidence pages.

See: https://docs.evidence.dev/core-concepts/templated-pages/

Minimal required NodeJS version for an Evidence app runtime is v16.14:

https://docs.evidence.dev/getting-started/install-evidence#system-requirements

• Check NodeJS presence and version prior to running any of the Evidence terminal commands
• Prompt a user to install NodeJS if no local installation is detected or it is older than v16.14

We'll split the multi-step install/run process triggered by dev server start into two separate actions to resolve hanging blank preview page issue.

• Show Install Dependencies in Evidence status bar if we can't find node_modules folder
• Install dependencies on the first run
• Change Evidence status bar to Start dev server as we have now after that npm install command step
• Update v1.0 changelog with this feature ticket info

Related: #4, #6 and #13.

Originally posted by @RandomFractals in #22 (comment)

• Use it to check for **/package.json in an open project folder and activate Evidence extension and commands, in addition to Evidence project detection and commands enablement checks from #18

Workspace Contains activation event docs:

https://code.visualstudio.com/api/references/activation-events#workspaceContains

Originally posted by @RandomFractals in #25 (comment)

• Link to Svelte for VSCode this extension depends on
• Describe what features Svelte dependency provides
• Add info about required Node.js version with download link
• Add brief Installation section to docs
• Add Evidence Installation image to docs
• Update changelog with this ticket info

Not urgent

Extend #2 to allow a user to create an evidence project without creating a new folder and opening it in vscode.

Flow I can imagine:

1. Open command Palette
2. Select "Create evidence project from template"
3. prompt boots up asking where you want to create the new project (with sensible default location?)
4. Then prompt continues to ask about what you are cloning (default is template)
5. New (or current) VSCode window boots into new project directory
6. Clone and install happens

The problem with the current emd language config is that it overwrites default markdown document Preview, Outline and rendering when .md documents are created or open in VS Code. See #9 for more info.

This should resolve currently missing standard markdown Outline display issue and will add extra elements to that side panel tree view for the Evidence web components and maybe frontmatter/header parts.

• Use VS Code Document Symbol Provider API: https://code.visualstudio.com/api/references/vscode-api#DocumentSymbolProvider

to open Evidence app settings file and change app configuration options in VSCode editor.

Evidence app settings file is used to configure app data sources.

The evidence.settings.json configuration file is located in .evidence/template folder.

Fine tuning -- not for current release

Command palette: "Start server"
Status bar tooltip: "Start dev server"

Command palette: "Stop server"
Status bar tooltip: "Stop dev server"

The command palette command should also be "start/stop dev server" IMO.

In either case, the terminology should be the same.

• Add getWorkspaceFolder() to src/config.ts
• Update all workspace.workspaceFolders[0] references and lookups in implemented commands, file utils, etc.

• Use built-in vscode env.asExternalUri to construct all app page Urls
• Detect remote app server hosting and add -- --host 0.0.0.0 param to npm run dev terminal command when starting dev server in Codespaces nodejs container
• Add using Evidence template with GitHub Codespaces in a browser to readme.md