@runfile/cli 0.39.1 → 0.41.0

package/README.md

@@ -629,14 +629,9 @@ $ run :generate zed-tasks
 $ run :generate jetbrains-run-configurations
 ```
 
-Pass `--stdout` to any of these to print the generated configuration to standard output instead of
-writing it to disk — handy for previewing, piping, or diffing in CI. The output is the freshly
-generated config (not merged with any existing file on disk) and nothing is created or modified.
-For `jetbrains-run-configurations`, which produces one file per target, each block is delimited by a
-`<!-- .run/<file> -->` comment when more than one is emitted.
-
-By default only the local Runfile's own targets are generated. Two independent flags widen the set,
-and both compose with `--stdout` and the on-disk writers:
+Each writes its editor's config to disk (`.vscode/tasks.json`, `.zed/tasks.json`, `.run/*.run.xml`),
+merging with any existing file. By default only the local Runfile's own targets are generated; two
+independent flags widen the set:
 
 - `--include-namespaces` also generates entries for targets pulled in via `includes` — namespaced
   targets carry their `namespace:` prefixes, exactly as `run :list` shows them (e.g. `run api:build`).
@@ -644,6 +639,39 @@ and both compose with `--stdout` and the on-disk writers:
   `run :config global-files` — the same ones `run :list` folds in. Handy when an editor integration
   should offer your machine-wide targets (e.g. `run c`, `run backup-git`) alongside a project's own.
 
+##### Building your own integration: `task-descriptors`
+
+For tooling that builds its **own** editor integration (like the
+[Runfile VS Code extension](https://github.com/JoaaoVerona/runfile)), there's an editor-agnostic
+alternative that always prints to stdout and never touches disk:
+
+```bash
+$ run :generate task-descriptors
+```
+
+It always resolves `includes` and merges registered global files (no `--include-*` flags), and emits
+a stable JSON document describing every runnable target grouped by its source file, with per-target
+provenance so a client can bucket local vs. included vs. global targets itself:
+
+```jsonc
+{
+  "formatVersion": 1,
+  "sources": [
+    {
+      "filePath": "/abs/path/Runfile.json",
+      "kind": "local",              // "local" | "included" | "global"
+      "targets": [
+        {
+          "name": "api:build",      // full canonical invocation name
+          "namespace": "api",       // omitted for un-namespaced targets
+          "description": "Build the API"
+        }
+      ]
+    }
+  ]
+}
+```
+
 Skip a target from the generated configs by setting `metadata.excludeFromGenerateCommand: true`. The
 `metadata` block on `globals` and on each target is **fully open** — any property of any JSON type
 (strings, numbers, booleans, arrays, deeply-nested objects) is accepted and round-trips untouched, so
@@ -656,6 +684,40 @@ output is formatted to match the settings that apply to each written path — th
 sets the newline sequence, `insert_final_newline` and `trim_trailing_whitespace` are applied, and
 `charset = utf-8-bom` prepends a BOM. When no `.editorconfig` applies, the previous defaults are kept.
 
+#### Preparation targets (like `npm prepare`, but enforced)
+
+Most projects have a one-time setup step — install git hooks, pull dependencies, generate config.
+It's easy to forget, and easy to fall behind when it changes. Point `globals.prepare` at a target and
+Runfile makes it a precondition for **every** target in the file:
+
+```jsonc
+{
+  "globals": { "prepare": "@setup" },
+  "targets": {
+    "setup": { "commands": ["git config core.hooksPath .githooks", "npm ci"] },
+    "build": { "commands": ["npm run build"] },
+    "test":  { "commands": ["npm test"], "prepare": "@setup-tests" },
+    "setup-tests": { "commands": ["./scripts/seed-test-db.sh"] }
+  }
+}
+```
+
+Run anything before setup has run and you get a clear stop, not a confusing failure:
+
+```console
+$ run build
+Error: target "build" requires preparation steps that haven't been completed:
+  • run setup    (never run)
+```
+
+Once you `run setup`, Runfile records a hash of its commands (following `@target` calls, so nested
+setups count too). Future runs pass silently — **until those commands change**, at which point the
+requirement re-triggers and everyone is prompted to re-run it. A target's own `prepare` is *additive*
+on top of the global one, so `run test` above requires both `setup` and `setup-tests`.
+
+Preparation is a developer-machine concern, so the gate is **skipped automatically in CI** (detected
+via `CI`, `GITHUB_ACTIONS`, and friends). Set `RUNFILE_SKIP_PREPARE=1` to bypass it manually.
+
 #### Migrate in seconds
 
 ```bash

package/bin/run.js

@@ -1,8 +1,7 @@
 #!/usr/bin/env node
-// Picks the bundled binary for the current platform/arch and execs it.
+
 const path = require('node:path');
 const { spawnSync } = require('node:child_process');
-
 const KEY = process.platform + '-' + process.arch;
 const BINARIES = {
   "linux-x64": "run",
@@ -12,8 +11,8 @@ const BINARIES = {
   "win32-x64": "run.exe",
   "win32-arm64": "run.exe"
 };
-
 const bin = BINARIES[KEY];
+
 if (!bin) {
 	console.error(`run: unsupported platform ${KEY}. Supported: ${Object.keys(BINARIES).join(', ')}`);
 	process.exit(1);
@@ -21,8 +20,10 @@ if (!bin) {
 
 const binPath = path.join(__dirname, KEY, bin);
 const result = spawnSync(binPath, process.argv.slice(2), { stdio: 'inherit' });
+
 if (result.error) {
 	console.error(`run: failed to spawn ${binPath}: ${result.error.message}`);
 	process.exit(1);
 }
+
 process.exit(result.status == null ? 1 : result.status);

package/package.json

@@ -13,5 +13,5 @@
 	"license": "MIT",
 	"name": "@runfile/cli",
 	"repository": "https://github.com/JoaaoVerona/runfile",
-	"version": "0.39.1"
+	"version": "0.41.0"
 }