@taskless/cli 0.10.2 → 0.11.1

package/dist/rules/platform-binary.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Resolving a prebuilt binary that ships as a per-platform npm package.
+ *
+ * This was ast-grep's resolver in `scan.ts`, generalized when Vale became a
+ * second engine that needs the same treatment. Both depend on per-platform
+ * packages directly and exec by path, because neither can rely on an
+ * install-time step: `@ast-grep/cli`'s postinstall hardlink fails under pnpm
+ * dlx's strict isolation, and the `@taskless/vale-*` packages deliberately ship
+ * no `bin` and no scripts at all.
+ *
+ * WHAT IS PARAMETERIZED, and why each field exists rather than being derived:
+ *
+ * - `toolchainSuffix` is the one that bites. ast-grep publishes
+ *   `@ast-grep/cli-linux-x64-gnu` and `-win32-x64-msvc`; the Vale packages are
+ *   `@taskless/vale-linux-x64` with **no libc suffix at all**. Reusing
+ *   ast-grep's naming for Vale would look up `@taskless/vale-linux-x64-gnu` and
+ *   miss on every Linux host — a resolution failure that reads as "Vale is not
+ *   installed" rather than as a naming bug.
+ * - `identity` exists because existence is not proof. A file can sit exactly
+ *   where the binary belongs and not be the binary: ast-grep's failed hardlink
+ *   leaves a placeholder text file there. Asking a candidate to identify itself
+ *   is the only check that tells the two apart.
+ */
+export interface PlatformBinarySpec {
+    /** Name used in error messages, e.g. `ast-grep`. */
+    label: string;
+    /** Package name up to the platform suffix, e.g. `@ast-grep/cli`. */
+    packagePrefix: string;
+    /**
+     * Append the platform's toolchain suffix (`-gnu` on Linux, `-msvc` on
+     * Windows). True for ast-grep, false for the Vale packages.
+     */
+    toolchainSuffix: boolean;
+    /**
+     * Executable names to try, in confidence order, spelled for unix. `.exe` is
+     * appended on Windows. More than one because ast-grep declares both
+     * `ast-grep` and `sg` for the same target.
+     *
+     * The first name is the canonical one: it is the only spelling probed inside
+     * the platform package, and it is the name error messages tell the user to put
+     * on PATH. The rest are alternative link names, tried *first* at the
+     * link-based tiers — see {@link resolvePlatformBinary}.
+     */
+    binaryNames: string[];
+    /** Pattern the candidate's own `--version` output must match. */
+    identity: RegExp;
+}
+/** The npm package carrying this host's prebuilt binary. */
+export declare function platformPackageName(spec: PlatformBinarySpec): string;
+/**
+ * The command name to tell a user to put on PATH, spelled for this platform
+ * (`sg.exe` on Windows). It is the first spelling the PATH search itself tries,
+ * so the advice and the search cannot drift apart.
+ */
+export declare function pathCommandName(spec: PlatformBinarySpec): string;
+/** First entry on PATH that holds a file named `command`. */
+export declare function findOnPath(command: string): string | undefined;
+/**
+ * Whether `path` is really this binary, established by running it.
+ *
+ * See {@link PlatformBinarySpec.identity} — existence is not enough, because a
+ * placeholder file left by a failed install sits at exactly the right path and
+ * satisfies `existsSync` happily.
+ */
+export declare function isPlatformBinary(spec: PlatformBinarySpec, path: string): boolean;
+/**
+ * Which tier produced a resolution.
+ *
+ * `platform-package` is the version this CLI pins and installs. The other two
+ * are whatever the host happens to carry, and can be any version.
+ */
+export type PlatformBinarySource = "platform-package" | "node_modules/.bin" | "PATH";
+export interface PlatformBinaryResolution {
+    /** Absolute path to the verified binary, or `undefined` when none resolved. */
+    path: string | undefined;
+    /**
+     * Which tier the path came from, or `undefined` when nothing resolved.
+     *
+     * **Identity is not provenance.** Resolution proves the file exists and
+     * answered `--version` as the right tool; it proves nothing about the
+     * version. Only `platform-package` is the pinned install, so only that tier
+     * entitles a caller to {@link AST_GREP_VERSION}-style constants without
+     * running the binary.
+     *
+     * Reported rather than left to be re-derived. A caller that needs the pinned
+     * engine would otherwise compare the returned path against a package root it
+     * reconstructs itself, which is this resolver's own search order copied into
+     * a consumer, and copies drift.
+     */
+    source: PlatformBinarySource | undefined;
+    /** Locations searched, in order, for an actionable failure message. */
+    tried: string[];
+}
+/**
+ * Search every place the binary could reasonably live, verifying each.
+ *
+ * Candidates are ordered by confidence rather than by convenience — the
+ * platform package first because it is the version we pinned, then a locally
+ * linked binary, then whatever the host provides on PATH.
+ *
+ * The platform package is probed under one name only. Its contents are ours to
+ * predict — the package ships the binary under its canonical name — so trying
+ * the alternative spellings there buys nothing but an extra `require.resolve`
+ * and a duplicate entry in `tried`, which reads to the user as the same
+ * location searched twice. The link-based tiers do try every spelling, because
+ * which one exists there is the installer's choice, not ours.
+ *
+ * Returns rather than throws. The two callers want different things from a
+ * miss: ast-grep cannot run at all without it, while a missing Vale binary
+ * makes one engine unavailable and must not abort the others (D6b). Encoding
+ * "not found" as a value rather than an exception is what lets each decide.
+ */
+export declare function resolvePlatformBinary(spec: PlatformBinarySpec): PlatformBinaryResolution;

package/dist/rules/vale/binary.d.ts

@@ -0,0 +1,35 @@
+import { type PlatformBinaryResolution, type PlatformBinarySpec } from "../platform-binary";
+/**
+ * Vale's per-platform packaging.
+ *
+ * `toolchainSuffix: false` is the whole reason this spec exists separately from
+ * ast-grep's. `add-vale-binary-packages` publishes `@taskless/vale-<os>-<cpu>`
+ * — `@taskless/vale-linux-x64`, not `-linux-x64-gnu`. ast-grep's resolver
+ * appends `-gnu` on every Linux, so reusing its naming here would resolve
+ * nothing on Linux while reporting the ordinary "Vale is unavailable" message,
+ * making a naming bug indistinguishable from a host without the binary.
+ *
+ * One binary name, unlike ast-grep's two: these packages ship `vale` (or
+ * `vale.exe`) as pure payload, with no `bin` entry and no lifecycle script, so
+ * there is no wrapper spelling to also try.
+ */
+export declare const VALE_BINARY: PlatformBinarySpec;
+/**
+ * Locate the Vale binary, or report that it is unavailable.
+ *
+ * Returns `undefined` rather than throwing, per D6b: a missing Vale binary
+ * makes the Vale engine unavailable and must not abort the other engines. The
+ * caller turns that into a reported-but-not-fatal outcome; ast-grep's resolver
+ * throws instead, because it has no degraded mode.
+ */
+export declare function findValeBinary(): PlatformBinaryResolution;
+/** Reset the process cache. Tests only. */
+export declare function resetValeBinaryCache(): void;
+/**
+ * An actionable message naming where we looked.
+ *
+ * The PATH advice is spelled for the platform — `vale.exe` on Windows — rather
+ * than hardcoded, so a Windows user is not told to install a name that the
+ * resolver would not find there.
+ */
+export declare function valeUnavailableMessage(tried: string[]): string;

package/dist/schemas/index.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Public entry for `@taskless/cli/schemas`.
+ *
+ * The shapes this CLI's `--json` output is produced from, as data. A consumer
+ * parsing `taskless verify --json` validates against the schema the CLI emits
+ * from, rather than against an interface it hand-wrote by reading our output
+ * once.
+ *
+ * ## Why this is published
+ *
+ * This is `@taskless/cli/layout`'s argument applied to the other half of the
+ * contract. A hand-written interface is a copy that nothing checks: the CLI can
+ * add a field, change what one means, or extend an enum, and the copy stays
+ * confidently wrong until something downstream misbehaves. The Cloud eval team
+ * is doing exactly that today against the `verify` envelope.
+ *
+ * ## What this is NOT
+ *
+ * Not an SDK. Nothing here performs verification, and no `verify()` or `test()`
+ * is exported. Both spawn a vendored platform binary — ast-grep or Vale — so
+ * anywhere a function call could run them, `npx @taskless/cli verify --json`
+ * runs too: the export would buy a call site, not a capability, while making
+ * internal signatures public. The CLI stays the execution surface; this
+ * describes what it says.
+ *
+ * Nothing here reaches the filesystem, a process, the network or the command
+ * tree, so a Worker can import it — and the build fails rather than emitting an
+ * entry whose graph reaches a host capability. `writeJsonError` is deliberately
+ * absent for that reason: it writes to stdout, and a consumer asking what shape
+ * an error takes should not thereby acquire something that emits one.
+ *
+ * ## Zod is bundled, and that is the point
+ *
+ * This entry ships its own copy of zod rather than resolving the consumer's.
+ * That follows from the build's standing rule for library entries — everything
+ * but node builtins is bundled — but it is also the behaviour we want, so do
+ * not "fix" it by making zod external.
+ *
+ * **A consumer's zod is not ours.** Marking it external would make validation
+ * depend on whichever version resolved on the other side, so the same payload
+ * could parse there and not here, and the schema would stop being a statement
+ * about what this CLI emits. Bundling makes `parse()` answer with our zod's
+ * semantics wherever it runs.
+ *
+ * **And `parse()` is stronger than a JSON Schema of the same shape.** It
+ * strips: `parse({ ok: true, rules: [], surprise: 1 })` returns
+ * `{ ok: true, rules: [] }`, where a JSON Schema validator hands back the
+ * object it was given, unknown keys included. Every schema here is plain today
+ * — objects, enums, arrays, optionals — so a JSON Schema rendering would lose
+ * little beyond that. It is the moment we add a refinement that the difference
+ * bites, and it would bite silently: the rendering would go on validating a
+ * weaker shape while claiming to describe this one.
+ *
+ * `z.toJSONSchema()` therefore stays unexported, and the criterion is the
+ * TRANSPORT rather than the consumer's language. JSON Schema is what you reach
+ * for when the schema itself has to travel — when the far side can receive JSON
+ * and nothing else, so a description of the shape is the most that fits. That
+ * is not this boundary. A consumer here takes a dependency on our schema files,
+ * which means it can assert the payload rather than assert against a
+ * description of the payload, and rendering ours down to what a JSON transport
+ * could carry would give that up in exchange for nothing.
+ */
+export { 
+/**
+ * `taskless verify --json` and `taskless test --json`.
+ *
+ * One envelope for both, because the commands share an implementation and
+ * differ only in what they run against each rule.
+ */
+outputSchema as verifyTestOutputSchema, } from "./verify-test.js";
+export { 
+/** `taskless rule verify <id> --json`, for an ast-grep rule. */
+verifyOutputSchema, 
+/** The same, for a Vale rule — a different shape, discriminated on `engine`. */
+valeVerifyOutputSchema, } from "./rules-verify.js";
+export type { 
+/**
+ * A constraint `verify` or `test` enforces beyond an engine's own schema.
+ *
+ * The type of the entries in `@taskless/cli/reference.json`'s
+ * `constraints[]`, so a consumer reading the corpus and a consumer reading a
+ * rejection are working from one definition.
+ */
+RuleConstraint, 
+/** One constraint a rule broke, as `violations[]` carries it. */
+RuleViolation, 
+/** The id of a constraint this CLI publishes. */
+RuleConstraintId, } from "../rules/constraints.js";
+export type { 
+/** The stable code an error envelope carries under `--json`. */
+CLIErrorCode, 
+/** The envelope itself. Not every `--json` failure is a rule result. */
+CLIErrorEnvelope, } from "../types/errors.js";

package/dist/schemas/rules-create.d.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+/** Input schema for `taskless rule create --from` JSON file */
+export declare const inputSchema: z.ZodObject<{
+    prompt: z.ZodString;
+    successCases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    failureCases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+/** Output schema for `taskless rule create --json` on success */
+export declare const outputSchema: z.ZodObject<{
+    success: z.ZodLiteral<true>;
+    ruleId: z.ZodString;
+    rules: z.ZodArray<z.ZodString>;
+    files: z.ZodArray<z.ZodString>;
+    notices: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+/** Error schema for `taskless rule create --json` on failure */
+export declare const errorSchema: z.ZodObject<{
+    error: z.ZodString;
+}, z.core.$strip>;

package/dist/schemas/rules-improve.d.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+/** Input schema for `taskless rule improve --from` JSON file */
+export declare const inputSchema: z.ZodObject<{
+    ruleId: z.ZodString;
+    guidance: z.ZodString;
+    references: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        filename: z.ZodString;
+        content: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+/** Output schema for `taskless rule improve --json` on success */
+export declare const outputSchema: z.ZodObject<{
+    success: z.ZodLiteral<true>;
+    requestId: z.ZodString;
+    rules: z.ZodArray<z.ZodString>;
+    files: z.ZodArray<z.ZodString>;
+    notices: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+/** Error schema for `taskless rule improve --json` on failure */
+export declare const errorSchema: z.ZodObject<{
+    error: z.ZodString;
+}, z.core.$strip>;

package/dist/schemas/rules-verify.d.ts

@@ -0,0 +1,67 @@
+import { z } from "zod";
+export declare const schemaOutputSchema: z.ZodObject<{
+    astGrepSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    tasklessRequirements: z.ZodObject<{
+        requiredFields: z.ZodArray<z.ZodString>;
+        rules: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            description: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    examples: z.ZodArray<z.ZodObject<{
+        description: z.ZodString;
+        rule: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const verifyOutputSchema: z.ZodObject<{
+    engine: z.ZodLiteral<"sg">;
+    success: z.ZodBoolean;
+    ruleId: z.ZodString;
+    schema: z.ZodObject<{
+        valid: z.ZodBoolean;
+        errors: z.ZodArray<z.ZodString>;
+        notice: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    requirements: z.ZodObject<{
+        valid: z.ZodBoolean;
+        errors: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+    tests: z.ZodObject<{
+        valid: z.ZodBoolean;
+        errors: z.ZodArray<z.ZodString>;
+        passed: z.ZodNumber;
+        failed: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/**
+ * Vale verification output.
+ *
+ * Deliberately not squeezed into the ast-grep shape. `sg` verification is three
+ * layers over a rule file and its test cases; Vale verification is one question
+ * asked of two fixture buckets — did every `fail/` document fire, did every
+ * `pass/` document stay quiet. Mapping the second onto `schema`/`requirements`/
+ * `tests` would invent two empty layers and lose the fixture coverage, which is
+ * the part that catches a rule that was never really verified.
+ *
+ * `engine` is the discriminant. A consumer branches on it before reading
+ * anything else, and adding an engine cannot silently change the meaning of a
+ * field another engine already emits.
+ */
+export declare const valeVerifyOutputSchema: z.ZodObject<{
+    engine: z.ZodLiteral<"vale">;
+    success: z.ZodBoolean;
+    ruleId: z.ZodString;
+    fixtures: z.ZodEnum<{
+        both: "both";
+        "pass-only": "pass-only";
+        "fail-only": "fail-only";
+        none: "none";
+    }>;
+    missingFailures: z.ZodArray<z.ZodString>;
+    unexpectedFindings: z.ZodArray<z.ZodString>;
+    notice: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const verifyErrorSchema: z.ZodObject<{
+    success: z.ZodLiteral<false>;
+    error: z.ZodString;
+}, z.core.$strip>;

package/dist/schemas/verify-test.d.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+/** Output schema for `taskless verify --json` and `taskless test --json`. */
+export declare const outputSchema: z.ZodObject<{
+    ok: z.ZodBoolean;
+    rules: z.ZodArray<z.ZodObject<{
+        engine: z.ZodEnum<{
+            sg: "sg";
+            vale: "vale";
+            runtime: "runtime";
+        }>;
+        ruleId: z.ZodString;
+        ok: z.ZodBoolean;
+        errors: z.ZodArray<z.ZodString>;
+        violations: z.ZodArray<z.ZodObject<{
+            constraintId: z.ZodString;
+            message: z.ZodString;
+        }, z.core.$strip>>;
+        ran: z.ZodOptional<z.ZodBoolean>;
+        refused: z.ZodOptional<z.ZodString>;
+        notice: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;