@taskless/cli 0.10.2 → 0.11.0

package/dist/prompts/index.d.ts

@@ -0,0 +1,89 @@
+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/*.txt` 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` 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.
+ */
+export declare const TOPICS: readonly ["create-sg-rule", "create-vale-rule", "create-runtime-rule"];
+/**
+ * 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: `route` picks an authoring
+ *   destination before the service is involved, `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.
+ */
+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"];
+/** 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,89 @@
+/** The canonical `<topic>.txt` 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;
+    /**
+     * 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;
+}
+/**
+ * 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 {
+    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;

package/dist/prompts.js

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