{"id":17382918,"url":"https://github.com/galvao-eti/shelly","last_synced_at":"2025-04-24T03:45:39.045Z","repository":{"id":256187317,"uuid":"850478491","full_name":"galvao-eti/shelly","owner":"galvao-eti","description":"A shell-like interface for the web written entirely in HTML, CSS and JavaScript (ES6).","archived":false,"fork":false,"pushed_at":"2024-09-27T12:12:48.000Z","size":1484,"stargazers_count":69,"open_issues_count":1,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-24T03:45:28.723Z","etag":null,"topics":["css","html","interface","shell","vanilla-javascript","web"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/galvao-eti.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","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":"2024-08-31T22:09:29.000Z","updated_at":"2025-04-15T15:24:12.000Z","dependencies_parsed_at":"2024-10-31T15:03:44.510Z","dependency_job_id":"66f5af55-6889-41eb-b7e3-3cdfe3f02d9f","html_url":"https://github.com/galvao-eti/shelly","commit_stats":null,"previous_names":["galvao-eti/shelly"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/galvao-eti%2Fshelly","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/galvao-eti%2Fshelly/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/galvao-eti%2Fshelly/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/galvao-eti%2Fshelly/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/galvao-eti","download_url":"https://codeload.github.com/galvao-eti/shelly/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250559994,"owners_count":21450168,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["css","html","interface","shell","vanilla-javascript","web"],"created_at":"2024-10-16T07:39:50.004Z","updated_at":"2025-04-24T03:45:39.029Z","avatar_url":"https://github.com/galvao-eti.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# shelly\n\n![Logo](media/logo.png)\n\nA shell-like interface for the web written entirely in HTML, CSS and JavaScript (ES6).\n\n- [shelly](#shelly)\n  - [Installation](#installation)\n  - [Usage](#usage)\n    - [shelly's expected flow (simplified):](#shellys-expected-flow-simplified)\n  - [CSRF](#csrf)\n  - [Server](#server)\n  - [Acknowledgements](#acknowledgements)\n  - [Credits](#credits)\n\n## Installation\n\n![Logo](media/screenshot.png)\n\n1. Get shelly from the releases page or clone this repository;\n2. Edit [public/src/config.js.dist](public/src/config.js.dist), set the right configuration values and edit the MOTD message (see the [wiki](https://github.com/galvao-eti/shelly/wiki) for more information);\n3. Save [public/src/config.js.dist](public/src/config.js.dist) as `public/src/config.js`;\n5. Add the CSS file to your HTML document:\n\n```html\n\u003clink rel=\"stylesheet\" href=\"style/shelly.css\"\u003e\n``` \n\n## Usage\n\nEither instantiate shelly as \"lazyInit\" or instantiate and then initialize it.\n\nThe following is the **recommended** way of using shelly:\n\n```html\n\u003cscript type=\"text/javascript\"\u003e\n    \"use strict\";\n\n    const configScript = document.createElement('script');\n    const commandsScript = document.createElement('script');\n\n    configScript.src = 'src/config.js?qs=' + Shelly.generateRandomString();\n    commandsScript.src = 'src/commands.js?qs=' + Shelly.generateRandomString();\n\n    document.body.appendChild(configScript);\n\n    configScript.addEventListener('load', function () {\n        document.body.appendChild(commandsScript);\n    });\n\n    commandsScript.addEventListener('load', function () {\n        // Programmatic Initialization\n        try {\n            const shelly = new Shelly(shellyConfig, false);\n            shelly.init();\n        } catch (e) {\n            console.error(e.message);\n        }\n\n        // Lazy Initialization\n        try {\n            const shelly2 = new Shelly(shellyConfig);\n        } catch (e) {\n            console.error(e.message);\n        }\n    });\n\u003c/script\u003e\n```\n\nshelly will then append it's elements to your HTML document's `body`.\n\nShelly transmits user input via a HTTP header called `SHELLY-INPUT`.\n\nPopulate shelly's `shellyCsrfToken` `meta` tag according to your anti-CSRF implementation (see [CSRF](#csrf) below);\n\n### shelly's expected flow (simplified):\n\n```mermaid\nflowchart LR\n    shelly --\u003e reqid[/request/]\n    reqid --\u003e API\n    API--\u003e resid[/response/]\n    resid --\u003e shelly\n```\n\nshelly can work with any HTTP backend, running on the same machine or via CORS. \n\nIf you provide a function named `processResponse`, shelly will automatically pass the response object to it. It will, otherwise:\n\n* Work with the main content of the response object as a `response` attribute, e.g. `data.response`;\n* Insert that response as HTML if the `Content-Type` response header includes `text/html`;\n* Insert that response as text otherwise.\n\n## CSRF\n\nIt should go without saying that **no one should use shelly without, at least, CSRF protection**.\n\nIf you need more information about CSRF there's no better place than [OWASP](https://owasp.org/www-community/attacks/csrf), of course.\n\nShelly expects to work with a CSRF token provided by the server. \n\nIt's beyond of the scope of shelly to tell you how to generate and deal with the CSRF token, since there are many methods to do this.\n\nThe token should be stored in a request header called, you've guessed it, `SHELLY-CSRF-TOKEN`. That header expects it's value to be read in an `content` attribute of a `meta` tag named `shellyCsrfToken`:\n\n```javascript\ndocument.head.querySelector('meta[name=shellyCsrfToken]').content;\n```\n\n## Server\n\na.k.a \"shelly-api\"\n\nThe server should implement:\n\n* CSRF prevention;\n* Validation;\n* A parser to break the input betwwen command, sub-command, flags, arguments, etc...\n* The processing and response of each command.\n\nI'll soon publish an example implementation and will then link it here.\n\n## Acknowledgements\n\n* shelly is a passion project and I dedicate it to my dear friend and master of shell [Julio Cezar Neves](https://pt.wikipedia.org/wiki/Julio_Cezar_Neves);\n* shelly's logo uses [Hack Nerd Font Mono](https://github.com/ryanoasis/nerd-fonts);\n* Every piece of diagram, drawing, logo, etc... was made in [inkscape](https://inkscape.org/);\n* The project's main resource for documentation is, of course, [Mozilla Developer Network](https://developer.mozilla.org/en-US/).\n\n## Credits\n\nCreated and maintained by [Er Galvão Abbott](https://github.com/galvao);\n \nLicensed under the Apcahe License by [Galvão Desenvolvimento Ltda](https://galvao.eti.br/) - see the [License file](/LICENSE).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgalvao-eti%2Fshelly","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgalvao-eti%2Fshelly","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgalvao-eti%2Fshelly/lists"}