@taskless/cli 0.10.2 → 0.11.1

package/README.md

@@ -1,235 +1,105 @@
 # @taskless/cli
 
-> A Work in Progress
+[![npm](https://img.shields.io/npm/v/@taskless/cli)](https://www.npmjs.com/package/@taskless/cli)
+[![build](https://img.shields.io/github/actions/workflow/status/taskless/cli/validate.yml?branch=main)](https://github.com/taskless/cli/actions/workflows/validate.yml?query=branch%3Amain)
+[![nightly](https://img.shields.io/badge/nightly-npm-blue)](https://www.npmjs.com/package/@taskless/cli-nightly)
+[![vale](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/taskless/cli/main/.shields/vale.json)](https://github.com/errata-ai/vale/releases)
+[![sg](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/taskless/cli/main/.shields/sg.json)](https://github.com/ast-grep/ast-grep/releases)
 
-CLI companion for [Taskless](https://taskless.io). Designed to be invoked by skills via `npx` or `pnpm dlx`. Useful for agents, and works for humans too.
+CLI companion for [Taskless](https://taskless.io). Designed to work with agent skills to add constraints that improve coding agent output.
 
-## Usage
+## Install
 
 ```bash
-# npm
-npx @taskless/cli@latest info
-
-# pnpm
-pnpm dlx @taskless/cli@latest info
-```
-
-## Commands
-
-### `taskless info`
-
-Outputs CLI version, tool status, and login info as JSON to stdout:
-
-```json
-{
-  "version": "0.0.3",
-  "tools": [],
-  "loggedIn": true,
-  "auth": { "user": "jake", "email": "jake@example.com", "orgs": ["my-org"] }
-}
-```
-
-### `taskless init`
-
-Launches an interactive wizard that detects supported tool directories in the
-current project (`.claude/`, `.opencode/`, `.cursor/`, `.agents/`), asks which
-tools to enable Taskless for, and walks through the auth tradeoff before
-writing anything. Running `taskless` with no subcommand in a TTY also launches
-this wizard. Without a TTY, bare `taskless` prints a short context preamble
-followed by the topic index from `taskless help`.
-
-In v0.7+, there is exactly one skill (`taskless`) and one command (`tskl`) —
-no opt-in selection needed.
-
-The skill and command content is written **once** to a canonical store in
-`.taskless/skills/` and `.taskless/commands/`. Each enabled tool directory
-receives only a thin reference stub — an ordinary file with a delegating body,
-never a symlink — so there is a single source of truth and no drift between
-copies. Stale layouts from earlier versions (full per-tool copies, symlinks)
-are converged into stubs automatically on the next `init`/`update`.
-
-For CI and scripted installs, pass `--no-interactive` to skip all prompts:
-
-```bash
-taskless init                    # interactive wizard (default in a TTY)
-taskless init --no-interactive   # scripted install, no prompts
+npx @taskless/cli
 ```
 
-The wizard records what it installed in `.taskless/taskless.json` so later
-runs can compute a diff and surgically remove files that are no longer
-selected. Upgrading from v0.6 automatically removes the obsolete per-task
-skills and commands during this diff. Cancelling the wizard at any step
-(Ctrl-C) aborts cleanly with no filesystem changes.
-
-### `taskless onboard`
-
-Post-install discovery flow that helps a fresh user go from zero rules to a
-useful starter set. Run it after `taskless init`. The CLI prints an
-agent-facing recipe that walks the host AI tool through scanning the
-codebase, agent-memory files (CLAUDE.md / AGENTS.md / .cursorrules),
-recent PR review comments (when `gh` is available), and issue tracker
-tickets (when a relevant MCP is wired in) for high-signal rule
-candidates, then surfaces them as a bullet list the user can choose to
-materialize via `taskless rule create`.
+Run with no arguments in a terminal to launch the installer, which detects the
+agent tools in your project (Claude Code, Cursor, OpenCode) and installs into
+each of them. For scripted installs, skip the prompts:
 
 ```bash
-taskless onboard                  # print the recipe (refused if already complete)
-taskless onboard --force          # re-run even when previously marked complete
-taskless onboard --mark-complete  # record completion in .taskless/taskless.json
-                                  # (invoked by the agent after explicit user
-                                  # confirmation; never automatically)
+npx @taskless/cli init --no-interactive
 ```
 
-Onboarding state lives in `.taskless/taskless.json` as
-`install.onboarded` — a 3-state optional field (absent / `false` / `true`).
-Only the agent writes it, and only with the user's explicit confirmation.
-`taskless init` does not set it. Pass `--force` to re-run regardless of the
-current value.
-
-After a successful `taskless init`, the CLI prints a one-line trailer
-pointing the user at this command. The trailer wording adapts to the
-install plan: when the install included slash commands (Claude Code or
-Cursor), it mentions `/tskl onboard` along with the Taskless skill and the
-bare CLI; when the install only wrote skills (OpenCode, Codex, the
-`.agents/` fallback), it mentions the skill and the bare CLI only.
+New to Taskless? Run `npx @taskless/cli onboard` after installing. It walks your
+agent through your codebase and suggests a starter set of rules.
 
-### `taskless check`
+## How to Use via Agents
 
-Run ast-grep rules from `.taskless/rules/` against the codebase. Exits with code 1 if any error-severity matches are found.
+Installing adds one skill (`taskless`) and one slash command (`/tskl`). The skill
+body is a small router: your agent fetches the canonical recipe for whatever you
+asked for, then follows it.
 
-```bash
-taskless check          # human-readable output, scans whole project
-taskless check --json   # JSON output
 ```
-
-Accepts optional positional path arguments to scan only specific files or
-directories — useful for CI workflows that only want to check changed files.
-Paths that don't exist on disk (e.g. files deleted in a diff) are silently
-filtered, so raw git-diff output can be piped in directly:
-
-```bash
-taskless check src/foo.ts src/bar.ts
-taskless check $(git diff --name-only main...HEAD)    # PR-only scan
-taskless check $(git diff --cached --name-only)       # pre-commit scan
+/tskl create a rule that bans console.log
+/tskl add taskless to CI
 ```
 
-If every supplied path is missing, the command exits 0 with empty results.
+Plain language works too: "write a taskless rule for X", "run taskless check",
+"taskless login" all engage the skill. You rarely need to run the CLI yourself.
 
-### `taskless auth login` / `taskless auth logout`
+To see what the agent sees, run `npx @taskless/cli agent` for the topic index, or
+`npx @taskless/cli agent <topic>` for a full recipe.
 
-Authenticate with taskless.io using the device flow. Tokens are stored in `~/.config/taskless/auth.json`.
+## Taskless Check (CI and Constraints)
 
-### `taskless rule create`
-
-Generate ast-grep rules via the taskless.io API. Reads a JSON request from stdin, submits it, polls for results, and writes rule and test files to `.taskless/rules/` and `.taskless/rule-tests/`.
+`taskless check` runs your rules against the codebase. It exits `0` when nothing
+error-severity matched and `1` when something did, so it drops straight into a
+pipeline:
 
 ```bash
-echo '{"prompt": "detect console.log usage"}' | taskless rule create
-echo '{"prompt": "find innerHTML assignments", "language": "typescript"}' | taskless rule create --json
+npx @taskless/cli check                                   # scan everything
+npx @taskless/cli check $(git diff --name-only main...HEAD)  # PR-only scan
+npx @taskless/cli check --json                            # machine-readable
 ```
 
-Requires authentication and a `.taskless/taskless.json` with `orgId` and `repositoryUrl`.
+Paths that no longer exist are dropped silently, so raw `git diff` output can be
+piped in without pre-filtering. Static rules need no login and make no network
+calls, so CI needs no secrets. Runtime rules (which execute code) only run once
+the server has verified their signature; otherwise they are reported as skipped
+and never change the exit code.
 
-### `taskless rule delete <id>`
+Ask your agent to `/tskl add taskless to CI` and it will wire this into the CI
+system you already use rather than replacing it.
 
-Remove a rule file and its associated test files from disk. No authentication required.
+## Why Teams Choose Taskless
 
-```bash
-taskless rule delete no-console-log
-```
+- **Constraints, not suggestions.** Rules are real files in your repo, enforced
+  by ast-grep, Vale, and runtime checks: the same result every run, for every
+  agent and every human.
+- **The same rules in the editor and in CI.** One command, one exit code.
+- **Works with the agent you already have.** One skill installs into Claude Code,
+  Cursor, and OpenCode, plus the `/tskl` command wherever the tool supports slash
+  commands, with a plain `.agents/` fallback when none is detected.
+- **Nothing to run locally.** No daemon, no install step in CI, no auth for the
+  checks that matter most.
 
-### `taskless --help`
+## Docs
 
-Lists available subcommands.
+- [docs.taskless.io](https://docs.taskless.io): guides and reference
+- [taskless.io](https://taskless.io): the product
+- [github.com/taskless/cli](https://github.com/taskless/cli): source and issues
 
-### `taskless help [topic]`
+<details>
+<summary><strong>Other</strong></summary>
 
-Returns agent-facing recipes. With no args, prints the topic index. With a
-topic (e.g. `taskless help rule create`), prints the full step-by-step recipe
-for that operation, including an embedded JSON Schema for any `--from` input
-and a table of stable error codes. Append `--anonymous` to fetch the
-local-only variant where one exists (currently `rule create`/`rule improve`).
+### Telemetry
 
-Recipes are how the consolidated `taskless` skill stays small while still
-covering every operation — the skill body is a router that fetches the
-relevant recipe on demand.
-
-### `--anonymous` flag
-
-Recognized on every command. Behavior matrix:
-
-- `rule create` / `rule improve` — exits with a pointer to
-  `taskless help <topic> --anonymous`. The local-only flow runs in the agent
-  per the recipe variant.
-- `info` — skips the API/auth probe; reports local state only.
-- `auth login` — rejected (auth commands cannot be anonymous).
-- All others — accepted as no-op.
-
-## For skill authors
-
-Skills should detect the package manager by checking for lock files and invoke the CLI accordingly:
-
-1. If `pnpm-lock.yaml` exists, use `pnpm dlx @taskless/cli@latest <command>`
-2. Otherwise, use `npx @taskless/cli@latest <command>`
-
-All commands output structured JSON to stdout by default. Parse with `JSON.parse()` and handle non-zero exit codes as errors.
-
-## Developing
-
-### Testing
+The CLI reports anonymous usage (which command ran, whether it succeeded, how
+long it took, and counts of findings. It never sends rule content, prompts, or
+matched source. Disable it by setting either environment variable:
 
 ```bash
-pnpm --filter @taskless/cli test                  # run the suite once
-pnpm --filter @taskless/cli exec vitest           # watch mode
+export TASKLESS_TELEMETRY_DISABLED=1
+# or the cross-tool convention
+export DO_NOT_TRACK=1
 ```
 
-The suite runs entirely locally under vitest — no network, no auth, no agent.
-Integration tests that exercise the built binary (for example `detect`) run
-against `dist/`, so run `pnpm --filter @taskless/cli build` first (or after any
-source change) before invoking them directly.
-
-**Two kinds of test, one of which is not fully automatable.** Most tests are
-deterministic unit/integration checks. The route-honesty dataset
-(`test/fixtures/route-eval.json`) is different: the actual routing decision is
-made by an _agent_ following `help/route.txt`, so it cannot be asserted by a
-code classifier. The automated test (`test/route-eval.test.ts`) therefore only
-**guards the dataset** — that it stays structurally valid and balanced across
-every route and both failure directions (over-claim / over-escalate). Running
-the dataset _as an evaluation_ — feeding each case to an agent and scoring its
-chosen destination — is a separate, manual calibration step with more setup; it
-is not part of `pnpm test`. Keep the two distinct: the suite proves the fixtures
-are well-formed; an agent run proves the recipe routes honestly.
-
-### API base URL
-
-The CLI resolves the API base URL in this order:
+With either set, no client is created and no network request is made.
 
-1. `TASKLESS_API_URL` env var
-2. `~/.config/taskless/config.json` → `apiUrl` field
-3. Default: `https://app.taskless.io/cli`
+</details>
 
-For local development against the taskless.io app:
-
-```bash
-TASKLESS_API_URL=http://localhost:5173/cli taskless info
-```
-
-### API schema introspection
-
-All `/cli/api/*` endpoints support the `x-explain: 1` header. When present, the endpoint returns its JSON schema instead of executing — no authentication required.
-
-```bash
-# List available endpoints
-curl -s -H "x-explain: 1" http://localhost:5173/cli/api
-
-# Get the schema for rule generation
-curl -s -H "x-explain: 1" -X POST http://localhost:5173/cli/api/rule
-
-# Get the schema for rule status polling
-curl -s -H "x-explain: 1" http://localhost:5173/cli/api/rule/any-id
-
-# Get the schema for whoami
-curl -s -H "x-explain: 1" http://localhost:5173/cli/api/whoami
-```
+---
 
-This is useful for verifying that CLI types align with the production API contract.
+MIT licensed.

package/assets/reference.json

@@ -0,0 +1,213 @@
+{
+  "version": 2,
+  "protocol": [
+    "Generate a rule from `prompt`, using your own pipeline.",
+    "Run `taskless verify` over what you generated. It enforces constraints beyond the engine's own schema, listed in `constraints` below, so a rule the engine executes correctly can still be refused. A rule that fails here is not deliverable however well it behaves, and every later step would be measuring the wrong thing. Check `enforcedBy` before concluding anything: some constraints are only decided once the fixtures run.",
+    "Run your generated rule against your own cases. It should pass; if it does not, the disagreement is inside your pipeline and nothing below will be informative.",
+    "Run your generated rule against `tests` here. A failure means your rule and ours disagree about the subject, and `tests` is the arbiter.",
+    "Run the rule in `rule` here against your cases. A failure means your cases and ours disagree, which is worth as much as the previous step and is the one nobody runs."
+  ],
+  "layout": {
+    "rulesRoot": ".taskless/rules",
+    "ruleDirectory": ".taskless/rules/{engine}/{id}",
+    "testsDirectory": ".tests",
+    "engines": {
+      "sg": {
+        "ruleFile": "{id}.yml",
+        "ruleConfigFile": null,
+        "capturesDirectory": null,
+        "fixtureLayout": "ast-grep-test"
+      },
+      "vale": {
+        "ruleFile": "{id}.yml",
+        "ruleConfigFile": ".vale.ini",
+        "capturesDirectory": null,
+        "fixtureLayout": "case-documents"
+      },
+      "runtime": {
+        "ruleFile": "check.ts",
+        "ruleConfigFile": null,
+        "capturesDirectory": "captures",
+        "fixtureLayout": "case-directories"
+      }
+    }
+  },
+  "constraints": [
+    {
+      "id": "sg-id-matches-directory",
+      "engine": "sg",
+      "enforcedBy": "verify",
+      "summary": "A rule's `id:` must equal the directory it lives in.",
+      "rationale": "The directory name is the rule id: it is what `check` and `test` address, and what a person types to delete a rule. ast-grep registers the rule under the id in its body. With the two apart, `test` cannot find the rule at all, and `check` does run it but reports findings under a name no directory has, so nobody can locate what produced them."
+    },
+    {
+      "id": "sg-regex-needs-kind",
+      "engine": "sg",
+      "enforcedBy": "verify",
+      "summary": "A `regex` needs a sibling `kind`, in `rule`, `constraints` and `utils`.",
+      "rationale": "A regex match with no kind to anchor it is ambiguous and slow: it is applied to every node rather than to the one shape the author meant. ast-grep accepts it, so the engine is not the thing that will tell you."
+    },
+    {
+      "id": "sg-language-accepted",
+      "engine": "sg",
+      "enforcedBy": "verify",
+      "summary": "`language:` must be a spelling ast-grep itself uses; a resolvable but non-canonical one is a notice.",
+      "rationale": "An unrecognized name aborts config parsing, which takes every other sg rule in the project down with it and reports nothing. That is the loudest possible failure with the quietest possible symptom: a clean report."
+    },
+    {
+      "id": "sg-files-globs-parse",
+      "engine": "sg",
+      "enforcedBy": "verify",
+      "summary": "`files:` globs must not name `.tsx` under TypeScript, or `.ts` under Tsx.",
+      "rationale": "A glob naming an extension the language cannot parse matches nothing, so the rule reports a clean codebase rather than an error. Only the TypeScript/Tsx pair is checked, and deliberately so: they are separate parsers rather than aliases, which is the one language/extension mismatch decidable from the rule file alone. No other extension is compared against `language`, so this is narrower than it first reads."
+    },
+    {
+      "id": "sg-required-fields",
+      "engine": "sg",
+      "enforcedBy": "verify",
+      "summary": "`id`, `language`, `severity`, `message` and `rule` are required.",
+      "rationale": "ast-grep needs fewer of these than we do. The extras are what make a finding actionable and a rule addressable once it is on disk."
+    },
+    {
+      "id": "sg-test-file-required",
+      "engine": "sg",
+      "enforcedBy": "verify",
+      "summary": "A rule must ship at least one test file under `.tests/`.",
+      "rationale": "A rule with no fixtures has shown neither that it fires nor that it stays quiet. `verify` requires the file; `test` requires the cases inside it to cover both."
+    },
+    {
+      "id": "sg-fixture-id-matches-rule",
+      "engine": "sg",
+      "enforcedBy": "test",
+      "summary": "A test file's own `id:` must equal the rule id.",
+      "rationale": "Fixtures are attributed by the id inside the file, not by its name. A fixture carrying another rule's id is silently not counted, so a rule that ships one reads as a rule that shipped none. `verify` passes, because the FILE is there; `test` is where it bites."
+    }
+  ],
+  "rules": [
+    {
+      "engine": "sg",
+      "id": "no-eval-call",
+      "directory": ".taskless/rules/sg/no-eval-call",
+      "ruleFile": "no-eval-call.yml",
+      "prompt": "Create a rule that flags any call to `eval()` in TypeScript.\n\nExecuting a string at runtime is an injection risk, and it defeats every static\nanalysis the project runs: nothing downstream can see what the code will do.\nPrefer a parser, a lookup table, or an explicit dispatch.\n\nDeciding this needs only the expression itself. No other file has to be read,\nand no state has to be resolved.\n\nCode that should NOT be flagged:\n\n```ts\nconst parsed = JSON.parse(payload);\n```\n\nCode that SHOULD be flagged:\n\n```ts\nconst result = eval(payload);\n```\n",
+      "rule": [
+        {
+          "path": "no-eval-call.yml",
+          "content": "id: no-eval-call\nlanguage: TypeScript\nseverity: error\nmessage: \"`eval` executes arbitrary code at runtime; use a parser or a lookup table instead.\"\nnote: |-\n  This is an example rule, shipped with the Taskless CLI to demonstrate the\n  `sg` tier. It was not written for this repository.\n\n  The evidence is one expression in one file, which is what makes this an `sg`\n  rule rather than a runtime one: no other file has to be read to decide it.\nrule:\n  pattern: eval($ARG)\n"
+        }
+      ],
+      "tests": {
+        "grouping": "ast-grep-test",
+        "files": [
+          {
+            "path": ".tests/no-eval-call-test.yml",
+            "content": "id: no-eval-call\nvalid:\n  - const parsed = JSON.parse(payload);\ninvalid:\n  - const result = eval(payload);\n"
+          }
+        ]
+      }
+    },
+    {
+      "engine": "vale",
+      "id": "prefer-use-over-utilize",
+      "directory": ".taskless/rules/vale/prefer-use-over-utilize",
+      "ruleFile": "prefer-use-over-utilize.yml",
+      "prompt": "Create a rule that flags the word \"utilize\" in markdown documentation and\nsuggests \"use\" instead.\n\n\"Utilize\" is longer than \"use\" and means the same thing in nearly every\nsentence a reader will meet. It should match case-insensitively and cover the\ninflected forms.\n\nThis is a prose rule. It applies to markdown, and it must not look at source\ncode.\n\nProse that should NOT be flagged:\n\n```md\nUse the installer to write the config file.\n```\n\nProse that SHOULD be flagged:\n\n```md\nUtilize the installer to write the config file.\n```\n",
+      "rule": [
+        {
+          "path": "prefer-use-over-utilize.yml",
+          "content": "extends: substitution\nmessage: \"Prefer '%s' over '%s'.\"\nlevel: warning\nignorecase: true\nswap:\n  utilize: use\n  utilizes: uses\n  utilizing: using\n"
+        },
+        {
+          "path": ".vale.ini",
+          "content": "# Scoped to markdown, which is where prose rules belong. A demonstration rule\n# should never widen its own scope into a project's source.\n[**/*.md]\nBasedOnStyles =\nprefer-use-over-utilize.prefer-use-over-utilize = YES\n"
+        }
+      ],
+      "tests": {
+        "grouping": "case-documents",
+        "files": [
+          {
+            "path": ".tests/pass/README.md",
+            "content": "# Setup\n\nUse the installer to write the config file.\n"
+          },
+          {
+            "path": ".tests/fail/README.md",
+            "content": "# Setup\n\nUtilize the installer to write the config file.\n"
+          }
+        ],
+        "cases": [
+          {
+            "bucket": "pass",
+            "name": "README.md",
+            "path": ".tests/pass/README.md",
+            "files": [".tests/pass/README.md"]
+          },
+          {
+            "bucket": "fail",
+            "name": "README.md",
+            "path": ".tests/fail/README.md",
+            "files": [".tests/fail/README.md"]
+          }
+        ]
+      }
+    },
+    {
+      "engine": "runtime",
+      "id": "env-keys-declared",
+      "directory": ".taskless/rules/runtime/env-keys-declared",
+      "ruleFile": "check.ts",
+      "prompt": "Create a rule that requires every environment variable read through\n`process.env` in a JavaScript or TypeScript file to have a matching key\ndeclared in the `.env` file at the repository root.\n\nReading a variable that is never declared is the failure worth catching: it is\n`undefined` at runtime rather than an error, so the program continues with a\nmissing value and fails somewhere else entirely.\n\nDeciding this needs both files at once — the read and the declaration — so it\ncannot be answered by matching a pattern within a single file.\n\nA repository that should NOT be flagged:\n\n```ts\n// src/config.ts\nexport const apiUrl = process.env.API_URL;\n```\n\n```\n# .env\nAPI_URL=https://api.example.com\n```\n\nA repository that SHOULD be flagged, on the second line only:\n\n```ts\n// src/config.ts\nexport const apiUrl = process.env.API_URL;\nexport const apiKey = process.env.API_KEY;\n```\n\n```\n# .env\nAPI_URL=https://api.example.com\n```\n",
+      "rule": [
+        {
+          "path": "check.ts",
+          "content": "/**\n * Every `process.env` read must have a matching key in the repository-root\n * `.env`.\n *\n * This is the demonstration rule, and its subject was chosen for one property:\n * the evidence spans two files. The read is in a source file, the declaration\n * is in `.env`, and no single-file pattern can compare them. A rule whose\n * evidence fits in one file is an `sg` rule, so a single-file subject would\n * demonstrate this tier by exercising none of what makes it a tier.\n *\n * It imports nothing from `@taskless/*`. The harness contract is structural —\n * a default-exported async function taking `(root, matches)` and returning\n * findings — so a delivered check never depends on a package being installed.\n */\n\nimport { readFileSync } from \"node:fs\";\nimport { join } from \"node:path\";\n\n/** One normalized ast-grep match, as the harness hands it over. */\ninterface Match {\n  /** The capture rule's stable name, which is what a check branches on. */\n  rule: string;\n  /** Path relative to `root`. */\n  file: string;\n  line: number;\n  column: number;\n  /** Captured metavariables by name. */\n  captures: Record<string, string>;\n}\n\n/** One result the check returns. */\ninterface Finding {\n  file: string;\n  line?: number;\n  column?: number;\n  message: string;\n  severity?: \"error\" | \"warning\" | \"info\";\n}\n\n/**\n * Keys declared in the repository-root `.env`, or none when it is absent.\n *\n * A missing `.env` yields an empty set rather than an error: a project with no\n * `.env` at all has declared nothing, which is exactly what the empty set\n * means, and every read in it is then correctly reported.\n */\nfunction declaredKeys(root: string): Set<string> {\n  let raw: string;\n  try {\n    raw = readFileSync(join(root, \".env\"), \"utf8\");\n  } catch {\n    return new Set();\n  }\n\n  const keys = new Set<string>();\n  for (const line of raw.split(\"\\n\")) {\n    const text = line.trim();\n    if (text === \"\" || text.startsWith(\"#\") || text.startsWith(\"//\")) continue;\n    const equals = text.indexOf(\"=\");\n    // `<= 0` rather than `=== -1`: a line beginning with `=` has no name.\n    if (equals <= 0) continue;\n    keys.add(text.slice(0, equals).trim());\n  }\n  return keys;\n}\n\nexport default async function check(\n  root: string,\n  matches: Match[]\n): Promise<Finding[]> {\n  const declared = declaredKeys(root);\n  const findings: Finding[] = [];\n\n  for (const match of matches) {\n    // Branch on the capture rule's NAME, never on its id: the id is a\n    // baked-in hash and is opaque to a check.\n    if (match.rule !== \"env-read\") continue;\n\n    const name = match.captures.VAR;\n    if (name === undefined || declared.has(name)) continue;\n\n    findings.push({\n      file: match.file,\n      line: match.line,\n      column: match.column,\n      message: `process.env.${name} is read here, but ${name} is not declared in .env`,\n      severity: \"error\",\n    });\n  }\n\n  return findings;\n}\n"
+        },
+        {
+          "path": "captures/env-read.yml",
+          "content": "# The syntactic narrow. It finds every `process.env.X` read; it cannot know\n# whether X is declared, because that answer lives in a different file. Deciding\n# is `check.ts`'s job, which is what makes this a runtime rule rather than an\n# `sg` one.\nid: env-read\nlanguage: TypeScript\nrule:\n  pattern: process.env.$VAR\nmetadata:\n  taskless:\n    version: 1\n    kind: runtime\n    name: env-read\n    check: check.ts\n    match: anchor\n"
+        }
+      ],
+      "tests": {
+        "grouping": "case-directories",
+        "files": [
+          {
+            "path": ".tests/pass/declared/src/config.ts",
+            "content": "// API_URL is read here and declared in .env, so this case is clean.\nexport const apiUrl = process.env.API_URL;\n"
+          },
+          {
+            "path": ".tests/pass/declared/.env",
+            "content": "API_URL=https://api.example.com\n"
+          },
+          {
+            "path": ".tests/fail/undeclared/src/config.ts",
+            "content": "// API_URL is declared; API_KEY is not, so the rule fires on the second.\nexport const apiUrl = process.env.API_URL;\nexport const apiKey = process.env.API_KEY;\n"
+          },
+          {
+            "path": ".tests/fail/undeclared/.env",
+            "content": "API_URL=https://api.example.com\n"
+          }
+        ],
+        "cases": [
+          {
+            "bucket": "pass",
+            "name": "declared",
+            "path": ".tests/pass/declared",
+            "files": [
+              ".tests/pass/declared/src/config.ts",
+              ".tests/pass/declared/.env"
+            ]
+          },
+          {
+            "bucket": "fail",
+            "name": "undeclared",
+            "path": ".tests/fail/undeclared",
+            "files": [
+              ".tests/fail/undeclared/src/config.ts",
+              ".tests/fail/undeclared/.env"
+            ]
+          }
+        ]
+      },
+      "signature": "1;h=sha-256;d=0000000000000000000000000000000000000000000000000000000000000000"
+    }
+  ]
+}

package/dist/binary-DSACXL6n.js

@@ -0,0 +1,107 @@
+import { spawnSync as v } from "node:child_process";
+import { existsSync as u } from "node:fs";
+import { createRequire as g } from "node:module";
+import { resolve as i, dirname as c } from "node:path";
+import { fileURLToPath as y } from "node:url";
+const R = {
+  label: "ast-grep",
+  packagePrefix: "@ast-grep/cli",
+  toolchainSuffix: !0,
+  binaryNames: ["ast-grep", "sg"],
+  identity: /ast-grep/i
+};
+function m(e) {
+  const r = [process.platform, process.arch];
+  return e.toolchainSuffix && (process.platform === "linux" ? r.push("gnu") : process.platform === "win32" && r.push("msvc")), `${e.packagePrefix}-${r.join("-")}`;
+}
+function o(e) {
+  return process.platform === "win32" ? `${e}.exe` : e;
+}
+function p(e) {
+  return e.binaryNames.toReversed();
+}
+function b(e) {
+  return o(p(e)[0] ?? e.label);
+}
+function P(e, r) {
+  try {
+    const a = g(import.meta.url).resolve(
+      `${m(e)}/package.json`
+    );
+    return i(c(a), r);
+  } catch {
+    return;
+  }
+}
+function h(e) {
+  const r = process.platform === "win32" ? ";" : ":";
+  for (const t of (process.env.PATH ?? "").split(r)) {
+    if (t === "") continue;
+    const a = i(t, e);
+    if (u(a)) return a;
+  }
+}
+function k(e, r) {
+  if (!u(r)) return !1;
+  const t = v(r, ["--version"], {
+    encoding: "utf8",
+    timeout: 5e3
+  });
+  return t.error !== void 0 || t.status !== 0 ? !1 : e.identity.test(`${t.stdout ?? ""}${t.stderr ?? ""}`);
+}
+function x(e) {
+  const r = i(
+    c(y(import.meta.url)),
+    "..",
+    "node_modules",
+    ".bin"
+  ), t = p(e), a = [
+    [
+      "platform-package",
+      m(e),
+      P(
+        e,
+        o(e.binaryNames[0] ?? e.label)
+      )
+    ],
+    ...t.map(
+      (n) => [
+        "node_modules/.bin",
+        "node_modules/.bin",
+        i(r, o(n))
+      ]
+    ),
+    ...t.map(
+      (n) => ["PATH", "PATH", h(o(n))]
+    )
+  ], l = [...new Set(a.map(([, n]) => n))];
+  for (const [n, , s] of a)
+    if (s !== void 0 && k(e, s))
+      return { path: s, source: n, tried: l };
+  return { path: void 0, source: void 0, tried: l };
+}
+const d = {
+  label: "vale",
+  packagePrefix: "@taskless/vale",
+  toolchainSuffix: !1,
+  binaryNames: ["vale"],
+  identity: /vale/i
+};
+let f;
+function T() {
+  return f ??= x(d), f;
+}
+function _(e) {
+  return `Vale binary not found. Looked in: ${e.join(", ")}. Install a supported platform build, or put \`${b(d)}\` on your PATH. Other engines still ran.`;
+}
+export {
+  R as A,
+  d as V,
+  m as a,
+  T as b,
+  h as f,
+  k as i,
+  b as p,
+  x as r,
+  _ as v
+};