@taskless/cli 0.10.2 → 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

@@ -0,0 +1,103 @@
+import { type RecipeOptions, type RecipeText } from "./recipes.js";
+/**
+ * Public entry for `@taskless/cli/prompts`.
+ *
+ * Everything here renders through the same embedded recipe text and the same
+ * render path `taskless agent <topic>` serves, so the two surfaces cannot emit
+ * different guidance. Nothing in this graph reaches the CLI runtime: no citty
+ * command tree, no telemetry, no filesystem or network, so a Worker can import
+ * it without dragging the CLI in behind it.
+ */
+/**
+ * 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/*.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.
+ *
+ * The list starts at what a consumer has actually asked for and grows on
+ * demand. It is the authoring recipe for each engine a rule can be routed to,
+ * so a consumer that can decide a rule belongs to an engine can also reach the
+ * procedure for writing one. Exporting a chooser without its destinations
+ * reproduces, for the platform generator, the dead end this surface exists to
+ * remove.
+ *
+ * `engine-selection` used to be exported alongside them. It no longer exists:
+ * 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", "route"];
+/**
+ * Recipes deliberately withheld from the export, recorded so they stay visible
+ * decisions rather than oversights. Two groups:
+ *
+ * - 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: `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` 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", "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. */
+export type PromptOptions = RecipeOptions;
+/**
+ * Render a prompt to finished text. Every `%(KEY)s` placeholder is resolved
+ * from values the package already holds, so the caller never handles a
+ * template dialect.
+ *
+ * @throws when the topic has no canonical recipe in the build, which means
+ * {@link TOPICS} and the recipe files have diverged.
+ */
+export declare function getPrompt(topic: PromptTopic, options?: PromptOptions): string;
+/**
+ * A prompt's text together with the sprintf variable names its template
+ * contains. The names come from `sprintf-js`'s own parse, not from a pattern
+ * match over the text.
+ */
+export type Instructions = RecipeText;
+/**
+ * Render a prompt and report which variables its template carries.
+ *
+ * `text` is byte-identical to {@link getPrompt} for the same arguments; the
+ * addition is `variables`, which tells a consumer what this topic's template
+ * was parameterized by without making them parse it.
+ *
+ * @throws when the topic has no canonical recipe in the build.
+ */
+export declare function getInstructions(topic: PromptTopic, options?: PromptOptions): Instructions;
+/**
+ * The **unrendered** template for a prompt, plus the variables it contains.
+ *
+ * Use this when the host knows a value the package cannot: which launcher the
+ * reader will actually use, which package manager the target repository runs.
+ * Render it with `sprintf-js`'s named-argument form; the text is the source
+ * template verbatim, so its `%%` escapes are intact and it is safe to render
+ * exactly once.
+ *
+ * @throws when the topic has no canonical recipe in the build.
+ */
+export declare function getRawInstructions(topic: PromptTopic, options?: PromptOptions): Instructions;
+/** Every exported topic as a render function, keyed by topic name. */
+export declare const PROMPTS: Record<PromptTopic, (options?: PromptOptions) => string>;

package/dist/prompts/recipes.d.ts

@@ -0,0 +1,114 @@
+/** 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 {
+    /**
+     * Select the `.anonymous` variant of the topic, falling back to the
+     * canonical recipe when the topic has no variant.
+     *
+     * @default false
+     */
+    anonymous?: boolean;
+    /**
+     * Value substituted for the `%(PACKAGE_MANAGER_DLX)s` placeholder. The
+     * default is an agent-fill marker, which is the right answer whenever
+     * the caller does not know the consuming repo's package manager.
+     *
+     * @default "<package-manager-dlx>"
+     */
+    packageManagerDlx?: string;
+    /**
+     * Value substituted for the `%(TASKLESS_CLI)s` placeholder: the full command
+     * a reader would type to run this CLI, launcher and package specifier
+     * included (`npx @taskless/cli@latest`, `pnpm dlx @taskless/cli-nightly@…`).
+     *
+     * THIS IS AN ARGUMENT, NEVER AN AMBIENT READ. Detecting the launcher needs
+     * `process.argv` and `process.env`, and this module is imported by Workers
+     * without `nodejs_compat`, where a module-scope `process` read throws at
+     * import time. `assert-prompts-graph` in `vite.config.ts` would not catch it
+     * either — `process` is a global, not an import — so the constraint is kept
+     * by shape: the CLI detects and passes the value in (see
+     * `src/util/package-manager.ts`), and a host that imports
+     * `@taskless/cli/prompts` passes nothing and gets the marker.
+     *
+     * Omitting it falls back to this build's own invocation when the build is
+     * not prod, and to the agent-fill marker otherwise.
+     *
+     * @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
+     * an LLM consumer whose prompt-cache key would otherwise churn on every
+     * CLI publish.
+     *
+     * @default true
+     */
+    header?: boolean;
+}
+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 {
+    text: string;
+    variables: string[];
+}
+/**
+ * Look up an agent recipe topic from the embedded recipe map and return the rendered
+ * text. Anonymous variants are preferred when `anonymous` is set and a
+ * variant exists; otherwise the canonical recipe is returned. Returns
+ * `undefined` when the topic is unknown.
+ */
+export declare function getRecipe(topic: string, options?: RecipeOptions): string | undefined;
+/**
+ * The **unrendered** template for a topic, plus the variables it contains.
+ *
+ * `text` is the source recipe with the build-target invocation rewrite applied
+ * and nothing else. The rewrite belongs here: it is build-target substitution
+ * rather than templating, and omitting it would make the raw text render to
+ * something the CLI never emits. Every `%(KEY)s` is left standing so a host
+ * that knows a value this package cannot know — its own launcher, its own
+ * package manager — can render the text itself.
+ *
+ * Returns `undefined` for an unknown topic, matching {@link getRecipe}. The
+ * public accessors in `./index.ts` turn that into a throw.
+ */
+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

@@ -0,0 +1,53 @@
+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",
+  "route"
+], s = [
+  "auth",
+  "check",
+  "ci",
+  "create-legacy-rule",
+  "create-remote-rule",
+  "delete-rule",
+  "detect",
+  "improve-rule",
+  "info",
+  "init",
+  "onboard",
+  "rule",
+  "rule-meta",
+  "update",
+  "verify-rule"
+];
+function a(e, r) {
+  return t(n(e, r), e);
+}
+function l(e, r) {
+  return t(i(e, r), e);
+}
+function d(e, r) {
+  return t(u(e, r), e);
+}
+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}.md behind it.`
+    );
+  return e;
+}
+const g = Object.fromEntries(
+  o.map((e) => [
+    e,
+    (r) => a(e, r)
+  ])
+);
+export {
+  s as INTERNAL_TOPICS,
+  g as PROMPTS,
+  o as TOPICS,
+  l as getInstructions,
+  a as getPrompt,
+  d as getRawInstructions
+};