@taskless/cli 0.11.0 → 0.11.2

package/README.md

@@ -16,10 +16,11 @@ npx @taskless/cli
 
 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:
+each of them. For scripted installs and upgrades, `init` runs the same install
+without prompts, in a terminal or not:
 
 ```bash
-npx @taskless/cli init --no-interactive
+npx @taskless/cli init
 ```
 
 New to Taskless? Run `npx @taskless/cli onboard` after installing. It walks your

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-DZahYwrf.js

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