@taskless/cli 0.11.0 → 0.11.1

package/dist/layout/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Public entry for `@taskless/cli/layout`.
+ *
+ * The rule layout table, as data: which engines exist, what file *is* the rule
+ * for each of them, where its per-engine config and capture rules live, and the
+ * directory names the whole tree hangs off. A rule is one directory,
+ * `.taskless/rules/<engine>/<id>/`, and this describes its contents.
+ *
+ * These are the same values the CLI itself dispatches on — not a copy kept in
+ * step, the actual module. Nothing here reaches the filesystem, the network,
+ * telemetry, or the command tree, so a Worker can import it; the build fails
+ * rather than emitting an entry whose graph reaches a host capability.
+ *
+ * ## Why this is published
+ *
+ * A service that builds a rule payload has to know what a complete rule is for
+ * a given engine. The alternative to importing it is transcribing it, and
+ * transcription drifts: the same layout was written into seven code comments
+ * and one specification here, all naming a path two migrations had already
+ * moved, and one of those stale comments carried the wrong layout into a
+ * cross-team design document before anyone noticed.
+ *
+ * ## What it does not tell you
+ *
+ * Only the shape. Whether a rule *runs* is a separate question with separate
+ * answers — a runtime rule executes only against a server-blessed signature
+ * over its `check.ts`, and a Vale rule fires only where its own `.vale.ini`
+ * scopes it. A file set that satisfies this table is well-formed, not
+ * necessarily live.
+ */
+export { ENGINES, ENGINE_LAYOUTS, RULES_DIRECTORY, RULE_TESTS_DIRECTORY, TASKLESS_DIRECTORY, isKnownEngine, type EngineExecutor, type EngineLayout, type EngineName, type FixtureLayout, } from "../rules/layout.js";

package/dist/layout.js

@@ -0,0 +1,43 @@
+const t = ["sg", "vale", "runtime"], r = "rules", i = ".taskless", n = ".tests", s = {
+  sg: {
+    engine: "sg",
+    ruleFile: (e) => `${e}.yml`,
+    ruleConfigFile: void 0,
+    capturesDirectory: void 0,
+    fixtureLayout: "ast-grep-test",
+    executor: "ast-grep"
+  },
+  vale: {
+    engine: "vale",
+    ruleFile: (e) => `${e}.yml`,
+    ruleConfigFile: ".vale.ini",
+    capturesDirectory: void 0,
+    fixtureLayout: "case-documents",
+    executor: "vale-runner"
+  },
+  runtime: {
+    engine: "runtime",
+    ruleFile: () => "check.ts",
+    ruleConfigFile: void 0,
+    // `captures/` rather than `matchers/`: "matcher" denotes a Vale `[<glob>]`
+    // config section elsewhere in this tree, and one word for two unrelated
+    // concepts is a cost paid at every future reading.
+    capturesDirectory: "captures",
+    // Directories, not documents. A runtime rule exists because its evidence
+    // spans more than one file, so a one-file case could not express the rules
+    // this tier is for.
+    fixtureLayout: "case-directories",
+    executor: "runtime-harness"
+  }
+};
+function u(e) {
+  return t.includes(e);
+}
+export {
+  t as ENGINES,
+  s as ENGINE_LAYOUTS,
+  r as RULES_DIRECTORY,
+  n as RULE_TESTS_DIRECTORY,
+  i as TASKLESS_DIRECTORY,
+  u as isKnownEngine
+};

package/dist/node/runtimes/index.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Public entry for `@taskless/cli/node/runtimes`.
+ *
+ * Where the engine binaries this CLI executes actually live on this host, and
+ * how to find them. It is the CLI's own resolver and the CLI's own package
+ * specs — not a copy kept in step, the actual modules — so a consumer that
+ * installs this package resolves the same ast-grep and the same Vale that
+ * `taskless check` would run.
+ *
+ * ## Why this is published
+ *
+ * A service that verifies a generated rule has to execute it, and a rule's
+ * behaviour is a property of the engine version that runs it, not of the
+ * version it was written against. ast-grep in particular changes what a capture
+ * matches across minors: a rule verified under one and executed under another
+ * can verify clean and then match nothing, which is a rule that passes its gate
+ * and never fires. Nothing reports that, because both sides succeeded.
+ *
+ * The alternative to importing this is pinning the engine version by hand
+ * alongside the CLI version, in a second place, and keeping the two in step.
+ * They drift, and the drift is silent in exactly the direction that matters.
+ * Installing this package and asking it where the binary is makes the engine
+ * version a consequence of the CLI version rather than a parallel fact: the
+ * pinned platform packages arrive as this package's own optional dependencies,
+ * and they move when the pin moves.
+ *
+ * ## This entry requires Node, and says so in its path
+ *
+ * `node/` is in the specifier deliberately. Resolution spawns each candidate to
+ * make it identify itself, reads the filesystem, and consults `PATH`, so this
+ * graph reaches `node:child_process`, `node:fs`, `node:module`, `node:path` and
+ * `node:url`. It will not run on a Worker or in a browser, and the import path
+ * says that before a build error has to.
+ *
+ * This is the difference between this entry and `@taskless/cli/prompts` and
+ * `@taskless/cli/layout`, which are host-free and whose builds fail if their
+ * graphs ever reach a host capability. Every published entry is classified as
+ * one or the other in `vite.config.ts`, and the build fails on an export
+ * belonging to neither, so this exemption is a declaration rather than an
+ * omission.
+ *
+ * ## Resolution reports a miss as a value, and each side decides what it means
+ *
+ * {@link resolvePlatformBinary} returns `{ path: undefined, tried }` when no
+ * candidate verified. It does not throw, and that is deliberate rather than
+ * incidental: `taskless check` runs several engines, and a host without Vale
+ * installed must lose the Vale rules rather than the whole run. Encoding "not
+ * found" as a value is what lets a caller choose.
+ *
+ * A verifier should choose the opposite. A sandbox whose optional dependency
+ * did not install resolves `undefined` for the same reason a developer's laptop
+ * does — nothing is there — but the consequence is not a skipped engine, it is
+ * a verification that ran no engine and reported success. Fail closed on
+ * `undefined`, and use `tried` to say where you looked:
+ *
+ * ```ts
+ * import {
+ *   AST_GREP_BINARY,
+ *   resolvePlatformBinary,
+ * } from "@taskless/cli/node/runtimes";
+ *
+ * const { path, tried } = resolvePlatformBinary(AST_GREP_BINARY);
+ * if (path === undefined) {
+ *   throw new Error(`ast-grep not resolved. Looked in: ${tried.join(", ")}`);
+ * }
+ * ```
+ *
+ * ## What a resolved path is, and is not
+ *
+ * It is a path that exists and that answered `--version` with output matching
+ * the spec's `identity`, so it is the binary and not a placeholder a failed
+ * install left behind.
+ *
+ * **It is not a promise about which version answered.** The first candidate
+ * tried is the pinned platform package, but a host that only has the engine on
+ * `PATH` resolves that instead, and that binary can be any version.
+ *
+ * `resolution.source` says which tier answered. Only `"platform-package"` is
+ * the pinned install, so only that value tells a caller the binary is the one
+ * this CLI ships:
+ *
+ * ```ts
+ * const { path, source } = resolvePlatformBinary(AST_GREP_BINARY);
+ * if (path === undefined) throw new Error("no engine");
+ * if (source !== "platform-package") throw new Error("not the pinned engine");
+ * // The binary at `path` is now known to be the pinned build.
+ * ```
+ *
+ * {@link isPlatformBinary} does NOT answer this. It checks that a file exists
+ * and answers `--version` as the right tool, which every tier satisfies by the
+ * time a path is returned. Identity is not provenance, and an earlier draft of
+ * this note said otherwise.
+ *
+ * **The pinned versions are deliberately not published here.** A consumer
+ * wanting to know it has the pinned engine should read `source`, which answers
+ * that directly and at resolution time. A version constant would answer it
+ * later and less well, by inviting a comparison against a number rather than a
+ * check of where the binary came from.
+ */
+export { findOnPath, isPlatformBinary, pathCommandName, platformPackageName, resolvePlatformBinary, type PlatformBinaryResolution, type PlatformBinarySource, type PlatformBinarySpec, } from "../../rules/platform-binary.js";
+export { AST_GREP_BINARY } from "../../rules/ast-grep-binary.js";
+export { VALE_BINARY } from "../../rules/vale/binary.js";

package/dist/node/runtimes.js

@@ -0,0 +1,10 @@
+import { A as s, V as m, f as o, i as e, p as f, a as t, r as i } from "../binary-DSACXL6n.js";
+export {
+  s as AST_GREP_BINARY,
+  m as VALE_BINARY,
+  o as findOnPath,
+  e as isPlatformBinary,
+  f as pathCommandName,
+  t as platformPackageName,
+  i as resolvePlatformBinary
+};

package/dist/prompts/index.d.ts

@@ -11,7 +11,7 @@ import { type RecipeOptions, type RecipeText } from "./recipes.js";
 /**
  * Topics exported as public API. Hand-maintained rather than derived from the
  * recipe files, because an exported name is a promise held for a major version
- * and a new `agent/*.txt` must not be able to publish one by existing. The
+ * and a new `agent/*.md` must not be able to publish one by existing. The
  * completeness check in `test/prompts.test.ts` asserts this list plus
  * {@link INTERNAL_TOPICS} accounts for every canonical recipe on disk.
  *
@@ -23,13 +23,28 @@ import { type RecipeOptions, type RecipeText } from "./recipes.js";
  * remove.
  *
  * `engine-selection` used to be exported alongside them. It no longer exists:
- * the criterion it carried now lives in `route`, stated once. `route` is not
- * exported yet because it still contains local mechanics (`taskless detect`,
- * on-device authoring) a Worker cannot run; until it is, a consumer gets each
- * destination's own scope from these three and adjudicates genuinely ambiguous
- * calls itself.
+ * the criterion it carried now lives in `route`, stated once.
+ *
+ * `route` was withheld on the grounds that it still contains local mechanics
+ * (`taskless detect`, on-device authoring) a Worker cannot run, and that a
+ * consumer could adjudicate ambiguous calls from the three destinations. Both
+ * halves were wrong in the same way.
+ *
+ * The mechanics are true and do not defeat it: a service consumer ignores
+ * them, which is a smaller adaptation than restating the criteria. And
+ * adjudicating from the destinations is what the platform generator actually
+ * tried. It hand-wrote the same judgement, arrived at `static | runtime` with
+ * nowhere to put `vale`, and generated every prose rule as an ast-grep rule
+ * while its own delivery layer could already serve a Vale one. `route` warns
+ * about exactly that conflation: whether a rule is static or runtime is one
+ * axis, and which engine authors it is another.
+ *
+ * That is the dead end named two paragraphs up, mirrored. Exporting a chooser
+ * without its destinations strands a consumer that can route but not author;
+ * exporting destinations without the chooser strands one that can author but
+ * not route, and it will write its own chooser rather than stop.
  */
-export declare const TOPICS: readonly ["create-sg-rule", "create-vale-rule", "create-runtime-rule"];
+export declare const TOPICS: readonly ["create-sg-rule", "create-vale-rule", "create-runtime-rule", "route"];
 /**
  * Recipes deliberately withheld from the export, recorded so they stay visible
  * decisions rather than oversights. Two groups:
@@ -37,13 +52,12 @@ export declare const TOPICS: readonly ["create-sg-rule", "create-vale-rule", "cr
  * - Command recipes (`auth` … `update`) walk an agent through running a CLI
  *   subcommand on a developer's machine. There is no caller for them outside
  *   the CLI that hosts those commands.
- * - Authoring recipes are unreachable server-side: `route` picks an authoring
- *   destination before the service is involved, `create-remote-rule` states
+ * - Authoring recipes are unreachable server-side: `create-remote-rule` states
  *   the boundary from the client's side, `detect` documents a CLI subprocess a
  *   Worker cannot spawn, `create-legacy-rule` targets a local toolchain, and
- *   `rule-meta` reads an `improve-rule` sidecar file.
+ *   `rule-meta` describes a local sidecar file the CLI never writes.
  */
-export declare const INTERNAL_TOPICS: readonly ["auth", "check", "ci", "create-legacy-rule", "create-remote-rule", "delete-rule", "detect", "improve-rule", "info", "init", "onboard", "route", "rule", "rule-meta", "update", "verify-rule"];
+export declare const INTERNAL_TOPICS: readonly ["auth", "check", "ci", "create-legacy-rule", "create-remote-rule", "delete-rule", "detect", "improve-rule", "info", "init", "onboard", "rule", "rule-meta", "update", "verify-rule"];
 /** A topic name the package exports. Unknown names fail to type-check. */
 export type PromptTopic = (typeof TOPICS)[number];
 /** Options accepted by every prompt render function. */

package/dist/prompts/recipes.d.ts

@@ -1,4 +1,4 @@
-/** The canonical `<topic>.txt` recipe names present in the build. */
+/** The canonical `<topic>.md` recipe names present in the build. */
 export declare function canonicalRecipeTopics(): string[];
 /** Options accepted by the shared render path. */
 export interface RecipeOptions {
@@ -37,6 +37,24 @@ export interface RecipeOptions {
      * @default "<taskless-cli>"
      */
     invocation?: string;
+    /**
+     * Render the steps that gather evidence by running this CLI.
+     *
+     * `false` replaces them with a statement of what the caller must supply
+     * instead. It exists because `invocation` cannot do this job: that option
+     * substitutes the BINARY NAME inside a command, so a consumer with no CLI
+     * setting it to a phrase renders `Run: <no CLI available> detect --json` — a
+     * malformed instruction rather than a clean absence, and worse than either
+     * honest answer.
+     *
+     * The evidence itself is not optional. A consumer that cannot run the
+     * commands still needs the linters, languages, rule styles, login state and
+     * owner, because the routing criteria are stated in terms of them. So this
+     * names what to supply rather than dropping the steps.
+     *
+     * @default true
+     */
+    mechanics?: boolean;
     /**
      * Include the `# Topic: <name> (CLI v<version> / topic vN)` first line.
      * Suppressing it drops the CLI version from the text, which matters to
@@ -47,17 +65,6 @@ export interface RecipeOptions {
      */
     header?: boolean;
 }
-/**
- * Render a recipe by interpolating sprintf-js named arguments. The recipe
- * source uses `%(KEY)s` placeholders; the variable table built here resolves
- * each known placeholder to its rendered string. Recipes that contain a
- * literal `%` character must escape it as `%%` per sprintf-js conventions.
- *
- * Two flavors of substitution coexist in the variables table:
- * - System-resolved values (e.g. `CLI_VERSION`) — rendered to a real value.
- * - Agent-fill markers (e.g. `PACKAGE_MANAGER_DLX`) — rendered as
- *   `<lower-kebab-name>` so the consuming agent knows to substitute.
- */
 export declare function buildVariables(content: string, topic: string, options?: RecipeOptions): Record<string, string>;
 /** A recipe's text plus the sprintf variables its template contains. */
 export interface RecipeText {
@@ -87,3 +94,21 @@ export declare function getRecipe(topic: string, options?: RecipeOptions): strin
 export declare function getRawRecipe(topic: string, options?: RecipeOptions): RecipeText | undefined;
 /** A topic's rendered text plus the variables its template contains. */
 export declare function getRenderedRecipe(topic: string, options?: RecipeOptions): RecipeText | undefined;
+/**
+ * Remove Vale's in-file directives from a recipe before anyone reads it.
+ *
+ * A recipe is checked by this repository's own Vale rules, and two of them
+ * teach through a worked example that quotes the words a shipped rule flags.
+ * `<!-- vale no-hedging.no-hedging = NO -->` marks that example so the rest of
+ * the file stays covered, which is only possible because a recipe is markdown.
+ *
+ * The directives are configuration, not content. Stripping happens HERE, where
+ * the embedded files are read into the maps, rather than at any of the three
+ * render entry points: one place to be correct, and `getRawRecipe` is covered
+ * by the same stroke as the rendered paths.
+ *
+ * The whole line goes, including its newline. Leaving a blank line behind
+ * would change the markdown a reader sees, which would make the exclusion
+ * mechanism visible in the output it exists to keep clean.
+ */
+export declare function stripValeDirectives(content: string): string;

package/dist/prompts.js

@@ -1,8 +1,9 @@
-import { H as n, a6 as i, a7 as u } from "./recipes-C_i98mTO.js";
-const a = [
+import { g as n, a as i, b as u } from "./recipes-w68swLg4.js";
+const o = [
   "create-sg-rule",
   "create-vale-rule",
-  "create-runtime-rule"
+  "create-runtime-rule",
+  "route"
 ], s = [
   "auth",
   "check",
@@ -15,13 +16,12 @@ const a = [
   "info",
   "init",
   "onboard",
-  "route",
   "rule",
   "rule-meta",
   "update",
   "verify-rule"
 ];
-function o(e, r) {
+function a(e, r) {
   return t(n(e, r), e);
 }
 function l(e, r) {
@@ -33,21 +33,21 @@ function d(e, r) {
 function t(e, r) {
   if (e === void 0)
     throw new Error(
-      `No recipe is embedded for prompt topic "${r}". This is a packaging fault: TOPICS lists a topic with no agent/${r}.txt behind it.`
+      `No recipe is embedded for prompt topic "${r}". This is a packaging fault: TOPICS lists a topic with no agent/${r}.md behind it.`
     );
   return e;
 }
-const f = Object.fromEntries(
-  a.map((e) => [
+const g = Object.fromEntries(
+  o.map((e) => [
     e,
-    (r) => o(e, r)
+    (r) => a(e, r)
   ])
 );
 export {
   s as INTERNAL_TOPICS,
-  f as PROMPTS,
-  a as TOPICS,
+  g as PROMPTS,
+  o as TOPICS,
   l as getInstructions,
-  o as getPrompt,
+  a as getPrompt,
   d as getRawInstructions
 };