{"id":13602385,"url":"https://github.com/3rd/auto","last_synced_at":"2025-05-07T11:46:49.834Z","repository":{"id":159885157,"uuid":"625363693","full_name":"3rd/auto","owner":"3rd","description":"Auto is a TypeScript-powered command-line automation tool.","archived":false,"fork":false,"pushed_at":"2024-12-05T01:18:21.000Z","size":412,"stargazers_count":13,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-13T17:52:27.984Z","etag":null,"topics":["automation","cli","command-line","scripting","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@andrei.fyi/auto","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/3rd.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":"2023-04-08T22:05:09.000Z","updated_at":"2025-03-03T15:27:02.000Z","dependencies_parsed_at":null,"dependency_job_id":"f8863bc1-9ed0-4dd4-aba5-01e453cc9d0f","html_url":"https://github.com/3rd/auto","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/3rd%2Fauto","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/3rd%2Fauto/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/3rd%2Fauto/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/3rd%2Fauto/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/3rd","download_url":"https://codeload.github.com/3rd/auto/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252873938,"owners_count":21817708,"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":["automation","cli","command-line","scripting","typescript"],"created_at":"2024-08-01T18:01:21.897Z","updated_at":"2025-05-07T11:46:49.810Z","avatar_url":"https://github.com/3rd.png","language":"TypeScript","readme":"# ![Logo](https://github.com/3rd/auto/assets/59587503/301898ff-8e00-4d53-b250-d710d380c42e) Auto\n\n[![NPM version](https://badgers.space/npm/version/@andrei.fyi/auto)](https://www.npmjs.com/package/@andrei.fyi/auto)\n[![License](https://badgers.space/github/license/3rd/auto)](https://github.com/3rd/auto/blob/master/LICENSE)\n![Contributions welcome](https://honey.badgers.space/badge/contributions/welcome/blue)\n\n**\u003cins\u003eAuto\u003c/ins\u003e** is a **TypeScript-powered command-line automation tool**.\n\\\nWrite and execute _global_ and _project-local_ scripts.\n\nIt's kind of like [zx](https://github.com/google/zx), but:\n\n- \u003cins\u003eTypeScript-focused\u003c/ins\u003e\n- Scripts are organized in \u003cins\u003erepositories\u003c/ins\u003e (no shebangs)\n- With many goodies\n\n![auto](https://github.com/3rd/auto/assets/59587503/5bc46d72-9372-4a2f-b286-2716e9062c3f)\n\nUse Auto to:\n\n- Generate files and projects\n- Create interactive scripts\n- Create context-aware automations\n\nExternal resources:\n\n- [Generating React Components with Auto - andrei.fyi](https://andrei.fyi/blog/auto-generating-react-components)\n\n\u003cbr/\u003e\n\n## Features\n\n- **TypeScript-powered**: Write scripts with TypeScript and enjoy full type-checking support.\n- **Global and local scripts**: Share scripts between projects or define project-specific scripts.\n- **Script parameters**: Auto turns script parameters into interactive prompts.\n- **Script validation \u0026 filtering**: Control the conditions for which a script is valid.\n- **Global utilities and helpers**: Auto injects several useful packages and custom helpers as globals.\n- **Context awareness**: Auto collects information about the project you're currently in.\n- **Auto-config**: Prompts to create a script repo and auto-configure `tsconfig.json`.\n- **REPL**: Useful REPL to explore the execution context, available globals, and scripts.\n\n## Installation\n\nAuto is published on NPM as [@andrei.fyi/auto](https://www.npmjs.com/package/@andrei.fyi/auto).\n\\\nIf you want to get the standalone experience, with global script support, you should install it globally.\n\\\nIf you only want to use it inside a project, you should install it locally.\n\n```sh\n# install Auto globally\nnpm install -g @andrei.fyi/auto # or pnpm, yarn, or your favourite tool\n\n# install Auto locally (and add a \"auto run [script-id]\" script in package.json)\nnpm install -D @andrei.fyi/auto\n```\n\n## CLI Usage\n\nYou can interact with Auto's CLI by running `auto` in your terminal:\n\n- **`auto ls`** - list the available scripts for the current context\n- **`auto run \u003cscript-id\u003e`** - run a script by `id`\n- **`auto repl`** - enter the REPL\n\n## Getting started (project)\n\nThis is a quick guide of how to setup Auto in your project:\n\n1. Install Auto as a development dependency.\n\n   ```sh\n   npm install -D @andrei.fyi/auto\n   ```\n\n2. Create an `auto` or `.auto` directory inside the project root.\n3. Run `auto ls` and allow Auto to auto-configure `./auto/tsconfig.json`.\n4. Create a script file `./auto/hello.ts`\n\n   ```ts\n   import \"auto\";\n\n   export default auto({\n     id: \"hello\",\n     title: \"Say Hello\",\n     run() {\n       console.log(\"Hello from an Auto script!\");\n     },\n   });\n   ```\n\n5. Run `auto ls` inside your project and notice how your script is listed.\n6. Run `auto run hello` to execute the script.\n\n## Script resolution\n\nWhen Auto runs, it first tries to find your scripts.\n\nFirst it looks for a global script repository, a directory located at:\n\n- `~/.config/auto` on Linux\n- `~/Library/Preferences/auto` on macOS\n- `%APPDATA%\\auto\\Config` on Windows _(why are you doing this to yourself?)_\n\nSecond, it tries to resolve the root of the project you may be in, based on your `cwd`.\n\\\nTo do this, it scans up the file tree until it finds a _project marker_ pattern, or reaches the root.\n\\\nIf there's no match, the current directory is considered the project root.\n\\\nCurrently the patterns it looks for are:\n[`package.json`, `go.mod`, `Makefile`, `.git`]\n\nThird, it looks for a local script repository, which is an `auto` or `.auto` directory, in the project root.\n\nFourth it loads all Auto scripts from both your global and local repositories.\n\\\nIf there is a local script that has the same `id` as a global script it overrides it.\n\\\nIf there are two scripts that share the same `id`, and the same locality, it panics.\n\n## Auto scripts\n\n\u003e Check out the [examples](examples) library for reference.\n\nAuto scripts are TypeScript modules that have their `default` export the result of an `auto(...)` call.\n\\\nThe `auto(...)` function is injected at runtime by `import \"auto\"`, which also imports the global types.\n\\\nBoth the `import \"auto\"` and `export default auto(...)` are required for scripts to work.\n\nThis is the skeleton of an Auto script:\n\n```ts\nimport \"auto\";\n\nexport default auto({\n  id: \"my-script\",\n  title: \"My Script\",\n  params: {\n    myParam: {\n      title: \"Component Name\",\n      type: \"string\", // \"string\" | \"number\" | \"boolean\"\n      required: true,\n      // defaultValue: ({ project, params }) =\u003e string|undefined\n    },\n  },\n  // isValid: (project) =\u003e project.hasDependency(\"something\"),\n  run: async ({ cwd, project, params, files, self, t, files, fileMap }) =\u003e {\n    //          ^ contextual variables and helpers\n    // instructions\n  },\n});\n```\n\nTo get a better understanding how it all ties together, you can look at the [type of a script](src/types.ts):\n\n```ts\nexport type Script\u003cP extends Record\u003cstring, ParamType\u003e\u003e = {\n  id: string;\n  title?: string;\n  params?: Params\u003cP\u003e;\n  isValid?: (project: Project) =\u003e boolean;\n  run: (args: {\n    cwd: string;\n    fileMap: Record\u003cstring, string\u003e;\n    files: { path: string; content: string }[];\n    params: { [K in keyof P]: ParamValueType\u003cP[K]\u003e };\n    project: Project;\n    self: Script\u003cP\u003e;\n    t: (text: string, params?: Record\u003cstring, string | number | boolean\u003e) =\u003e string;\n  }) =\u003e void;\n};\n```\n\n### Contextual variables and helpers\n\nYour script's `run()` function is called with a dictionary that contains the following contextual variables and helpers:\n\n- **`cwd: string`** - The directory you called `auto` from.\n- **`fileMap: Proxy\u003c{}\u003e`** - proxied map that resolves the content of files, relative to the script file\n  - For example, if your script is `special.ts`, and there is a directory `interests` next to it, and there's a file named `rule.txt` inside it, you can get its content by accessing `fileMap[\"interests/rule.txt\"]`.\n- **`files: { path, content }[]`** - the deeply-listed list of files inside the directory the current script is in.\n  - Note: the current script file will not be included in `files`\n- **`params: Record\u003ckey,value\u003e`** - dictionary of your script's param keys and user-provided values.\n- **`project: Project`** - The current `Project`, a small abstraction that provides some helpers:\n  - **`Project.isGoProject`** - `true` in a Go project\n  - **`Project.isTypeScriptProject`** - `true` in a TypeScript project\n  - **`Project.isJavaScriptProject`** - `true` in a JavaScript project\n  - **`Project.isNodeProject`** - `true` in a Node.js project (shallow, checks for `@types/node`)\n  - **`Project.dependencies`** - `{ name, version }[]` of dependencies for Go and JS projects\n  - **`Project.hasDependency(name, version?)`** - checks if the project has a dependency\n  - **`Project.hasAnyDependency(names)`** - checks if the project has any of a list of dependencies (by name)\n  - **`Project.resolvePath(...paths)`** - resolve a path relative to the project root\n  - **`Project.hasPath(...paths)`** - resolve and check if a project-relative path exists\n  - **`Project.hasFile(...paths)`** - resolve and check if a project-relative path is a file\n  - **`Project.readFile(path)`** - read a project-relative file\n  - **`Project.readJSON(path)`** - read a project-relative JSON file\n  - **`Project.writeFile(path, content)`** - write a project-relative file\n  - **`Project.hasDirectory(...paths)`** - resolve and check if a project-relative path is a directory\n  - **`Project.createDirectory(path)`** - create a project-relative directory\n- **`t(text, data?: { [key]: value })`** - helper string templating function that replaces `__key__` with the provided value\n  - Note: If no data is provided, it uses the `params` dictionary.\n- **`self: Script`** - the current script itself, useful for introspection ~~and meditation~~\n\n### Globals\n\nAuto injects many helpers into the [global scope](src/globals/index.ts).\n\n**External helpers:**\n\n- **`$`**, **`$$`**, **`execa`**, **`execaSync`** - process execution utilities provided by [execa](https://github.com/sindresorhus/execa)\n- **`chalk`** - [chalk](https://github.com/chalk/chalk)\n- **`fs`** - [fs-extra](https://github.com/jprichardson/node-fs-extra)\n- **`glob`** - [glob](https://github.com/isaacs/node-glob)\n- **`lodash`** - [lodash](https://github.com/lodash/lodash)\n- **`which`** - [which](https://github.com/npm/node-which)\n- **`inquirer`** - [@inquirer/prompts](https://github.com/SBoudrias/Inquirer.js/), also aliased to `prompt`\n\n**Internal helpers:**\n\n- **`sleep(milliseconds: number): Promise\u003cvoid\u003e`**\n- shell-like helpers: **`cwd()`**, **`cd()`**, **`pwd`**\n\n## Contributing\n\nContributions to the Auto project are welcome!\n\\\nWhether it's a bug report, a new feature, or feedback on the project, I'd love to hear from you.\n","funding_links":[],"categories":["cli"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F3rd%2Fauto","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F3rd%2Fauto","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F3rd%2Fauto/lists"}