{"id":17153712,"url":"https://github.com/pq/scry","last_synced_at":"2026-01-18T02:02:15.089Z","repository":{"id":150126713,"uuid":"140046141","full_name":"pq/scry","owner":"pq","description":" a lightweight lua language server for norns.","archived":false,"fork":false,"pushed_at":"2018-07-21T18:26:42.000Z","size":1306,"stargazers_count":1,"open_issues_count":5,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-06T04:17:51.846Z","etag":null,"topics":["lua","monome","norns"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pq.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-07-07T02:24:44.000Z","updated_at":"2021-09-23T14:28:26.000Z","dependencies_parsed_at":"2023-04-04T16:47:11.856Z","dependency_job_id":null,"html_url":"https://github.com/pq/scry","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/pq/scry","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pq%2Fscry","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pq%2Fscry/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pq%2Fscry/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pq%2Fscry/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pq","download_url":"https://codeload.github.com/pq/scry/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pq%2Fscry/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28526560,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T00:39:45.795Z","status":"online","status_checked_at":"2026-01-18T02:00:07.578Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["lua","monome","norns"],"created_at":"2024-10-14T21:47:05.689Z","updated_at":"2026-01-18T02:02:10.076Z","avatar_url":"https://github.com/pq.png","language":"Lua","readme":"# scry\n\na lightweight lua language server for [norns](https://github.com/monome/norns).\n\n### advises\n\nscry flags syntax errors, identifies common control and data flow issues,  highlights implicitly defined globals, overwritten or mutated protected norns global state, unused or shadowed variables and more.  behind the scenes scry uses [lua_check](https://github.com/mpeterv/luacheck) for linting and analysis and provides all of it’s supported [warnings](https://luacheck.readthedocs.io/en/stable/index.html).\n\n\n![alt text](https://github.com/pq/scry/blob/master/docs/images/demo_advise.gif \"scry advises\")\n\n\n### mends\n\nscry builds on the [lua_code_formatter](https://github.com/martin-eden/lua_code_formatter) to provide simple on-demand code formatting for selections or entire documents.\n\n![alt text](https://github.com/pq/scry/blob/master/docs/images/demo_mend.gif \"scry mends\")\n\n\n### sees\n\n*(planned)* scry provides access to lua and sc docs.\n\n---\n\n\n## implementation\n\nscry runs as a small lightweight server process.  maiden connects to scry via a web socket.  \n\n* on source changes, editor contents are sent to scry for analysis; advice comes back as a list of “issues” that are translated into editor gutter annotations and inline source markers. syntax errors appear in red and warnings in yellow. blue markers flag norns callback implementations for easy identification.\n\n* on demand, editor selections (or full contents) are sent to scry for mending with a keystroke (⌘-SHIFT-F); a tidy, well formatted result replaces unruly editor contents.\n\t \nthe smarts of scry are written in lua and leverage proven modules.  scry is  tiny, scalable and simple to extend.\n\n\t\n## motivation and background\n\nmaiden uses a customized [ace editor](https://ace.c9.io/) mode to provide an editing experience tailored to lua for norns.  out of the box, ace provides basic client-side syntax highlighting and a web-worker-based syntax checker. \n\nthe design of ace only allows for limited customization.  notably, the syntax checker is not easily enhanced or replaced. work on the client-side has fundamental limitations as well.  doing semantic analysis in the browser (to provide, for example, awareness of norns functions or offer lua linting), is not practical.  nor is rich code transformation (such as formatting or refactoring).  scry works around these shortcomings by migrating analysis to a lightweight server process.\n\n## features\n\nbeyond the basic ace editor lua support, scry adds:\n\n* lua 5.3 syntax awareness\n* lua and norns-specific semantic analysis\n* a host of analyses and lints\n* inline source markers\n* on-demand formatting\n\nplanned improvements include:\n\n* improved norns-aware code analyses\n* improved error / lint messages\n\nmore ambitiously, another mode (\"see\") for\n\n* serving documentation\n\n\n## running scry\n\nrunning scry involves setting up two parts. \n\n**scry server.** a process that manages a web socket that serves requests to “advise” and “mend” to maiden.\n\n**scry maiden.** a version of maiden, tailored to listen to advice from a scry server.\n\ntrying out scry involves running a local scry server and local maiden dev server instance.  maiden will point to matron and sc repls on your norns device so you can edit and run your scripts in dust.\n\n### scry server\n\n**get the source.** clone or download the [scry repo](https://github.com/pq/scry).\n\n**setup.** first you’ll need to get some lua libraries installed to do the heavy-lifting:`luacheck` (for static analysis) and `lcf` (for formatting).\n\n**run.**\n\n0. make sure you have lua installed locally (e.g., on mac os,  `brew update; brew install lua`) \n1. the default installation also provides `luarocks`, a lua package manager.  use it to install our library dependencies: `luarocks install luacheck; luarocks install lcf`\n\nscry needs a server process to manage the web-socket connection w/ maiden.  included is a simple server using `node`.  (to be replaced.)\n\n0. make sure node is installed (on mac os, `brew install node`)\n1. use the node package manager to add a simple web socket library: `npm install --save ws`\n\nfinally, start scry:\n\n`node server.js`\n\n(you’ll want to keep this open in a dedicated terminal window or tab — aside, if you’re on mac os, consider the excellent free terminal replacement  [iTerm2](https://www.iterm2.com/index.html).)\n\n\n### scry maiden\n\n**get the source.** check out the `scry` branch of my [maiden fork](https://github.com/pq/maiden) for a version of maiden that integrates with scry. follow the steps in the general maiden [README](https://github.com/monome/maiden/blob/master/README.md) to install deps, etc.\n\n**run.**\n\n0. be sure wifi is enabled on `norns` (system \u003e wifi menu)\n1. note the ip address (visible in the wifi menu once connected); alternatively if `norns.local` resolves for you (`ping norns.local`), prefer that.\n2. update `app/public/repl-endpoints.json`  replacing `maiden_app_location`to point at your norns ip address. (here on we’ll use `norns.local`)\n3. mount your `norns` locally (on mac os, `sshfs we@norns.local: ~/norns-mnt`)\n4. (in a terminal window) start the backend: `go build \u0026\u0026 ./maiden -app app/build/ -data ~/norns-mnt/dust -doc ~/norns-mnt/norns/doc -debug`\n5. (in another terminal) start the dev server:  `cd app; yarn start`\n6. point your web browser at the dev server: `http://localhost:3000/`\n\n\n\n## next steps\n\n- [ ] tune analysis for norns ([#1](https://github.com/pq/scry/issues/1))\n- [ ] migrate to a more native server wrapper (using `ws-wrapper`, go or lua web sockets) ([#4](https://github.com/pq/scry/issues/4))\n- [ ] evaluate norns lua dependency installation options ([#5](https://github.com/pq/scry/issues/5))\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpq%2Fscry","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpq%2Fscry","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpq%2Fscry/lists"}