@ttctl/cli 0.1.0-rc.6 → 0.1.0-rc.8

package/dist/commands/jobs/apply.d.ts

@@ -0,0 +1,194 @@
+import { applications } from "@ttctl/core";
+import type { OutputFormat } from "../../lib/output.js";
+/**
+ * Options for `ttctl jobs apply <id>` (#430). The CLI verb lives on
+ * `jobs` (reads naturally: "apply to a job") while the underlying
+ * service module is `applications.apply` per ADR-008 § Decision Part 5.
+ *
+ * `--consent` is the user-side legal-compliance attestation locked by
+ * ADR-008 § Decision Part 4 — absence raises `CONSENT_REQUIRED` BEFORE
+ * any wire call. Auto-filling this field is forbidden.
+ *
+ * `--answers-file` / `--pitch-file` follow the ADR-008 § Decision Part 2
+ * JSON-file grammar (sibling to `applications confirm` per #428): a
+ * path (or `-` for stdin) pointing at a JSON document; the wrapper
+ * shape AND inner content are validated against the recovered Zod
+ * schemas per #438 Stage-2 before any wire call.
+ */
+export interface JobsApplyOptions {
+    /**
+     * Legal-compliance attestation per ADR-008 § Decision Part 4. MUST be
+     * supplied by the user — auto-filling is forbidden. Absence raises
+     * `CONSENT_REQUIRED` with no wire call issued.
+     */
+    consent?: boolean;
+    /**
+     * Optional hourly rate the talent requests (decimal string, matches
+     * `BigDecimal!`). When omitted, the service defaults from
+     * `PreApplyData.suggestedRate` (REQ-A4). When supplied, must pass the
+     * `DECIMAL_PATTERN` regex.
+     */
+    rate?: string;
+    /**
+     * Optional talent-side free-text accompanying message. Forwarded to
+     * `applications.apply` as `message`, which maps to the wire
+     * `$comment` variable on the `JobApply` mutation.
+     */
+    message?: string;
+    /**
+     * Path to a JSON file (or `-` for stdin) containing
+     * `{ matcherAnswers: [...], expertiseAnswers: [...] }` per ADR-008
+     * § Decision Part 2. Wrapper shape AND inner items validated against
+     * the recovered Zod schemas before any wire call (#438 Stage-2).
+     */
+    answersFile?: string;
+    /**
+     * Path to a JSON file (or `-` for stdin) containing a `PitchInput`
+     * object. Forwarded to `applications.apply` as `pitchData`, mapping
+     * to the wire `$talentCard` variable. Validated against the recovered
+     * `PitchInputSchema` (#438 Stage-2); extra unknown keys reject with a
+     * field-path error.
+     */
+    pitchFile?: string;
+    /**
+     * Preview-only flag (REQ-Q3). When set, fetches `applyData` +
+     * `applyQuestions` and emits the inventory WITHOUT issuing the
+     * `JobApply` mutation. Does NOT require `--consent` (read-only
+     * path; never reaches the apply mutation).
+     */
+    showQuestions?: boolean;
+    /**
+     * Opt-in autocomplete suggestion fetch (REQ-Q4 / #452). When set,
+     * issues an additional `SimilarJobQuestionAnswers` fan-out in
+     * addition to the standard 3-query pre-apply suite and renders the
+     * historical similar answers in the output. NEVER auto-fills the
+     * `--answers-file` payload — suggestions are advisory only.
+     *
+     * The suggestion fetch fans out N parallel calls (one per matcher
+     * + expertise question). Per scenario "Suggestion query fails —
+     * apply continues without suggestions", failures of the suggestion
+     * branch surface as a stderr warning and the apply path continues
+     * unchanged.
+     *
+     * Works in `--dry-run` mode: the suggestion query is suppressed
+     * (zero wire calls under dry-run, matching the standard apply
+     * dry-run posture). Set this with `--show-questions` to also
+     * suppress the apply mutation (suggestion fetch runs against the
+     * applyQuestions inventory and is reported alongside the question
+     * preview).
+     */
+    suggestAnswers?: boolean;
+    output: OutputFormat;
+}
+/**
+ * Projection emitted on the `--show-questions` preview path. Carries
+ * the pre-apply context (canApply, applyErrors, suggestedRate,
+ * rateValidation) alongside the matcher + expertise question
+ * inventories so the user can author an `--answers-file` payload
+ * without a separate command. The shape is distinct from the
+ * service-layer's {@link applications.PreApplyData} /
+ * {@link applications.ApplicationQuestions} types so consumers
+ * don't have to reach across two type namespaces.
+ */
+interface ShowQuestionsProjection {
+    jobId: string;
+    canApply: boolean;
+    applyErrors: applications.ApplyError[];
+    suggestedRate: string | null;
+    rateValidation: {
+        minRate: string;
+        rateStep: number;
+    } | null;
+    matcherQuestions: applications.ApplicationQuestion[];
+    expertiseQuestions: applications.ApplicationQuestion[];
+    /**
+     * Optional autocomplete suggestions (#452). Populated when
+     * `--suggest-answers` is set; absent otherwise. One group per
+     * question (matcher + expertise, interleaved in the same order as
+     * the inventory). Each group's `suggestions` array carries the
+     * talent's own historical answers to semantically-similar questions.
+     * Empty arrays surface verbatim when the talent has no similar-job
+     * history for that question.
+     */
+    suggestions?: applications.SimilarJobAnswerGroup[];
+}
+/**
+ * Apply-success envelope extension (#452). When `--suggest-answers`
+ * is passed alongside an actual apply (NOT `--show-questions`), the
+ * apply outcome surfaces the post-apply `JobApplicationRecord` AND
+ * the historical suggestions that would have been useful to author
+ * the answers-file (rendered as a sibling section in the pretty
+ * output). The shape is distinct from the bare
+ * {@link applications.JobApplicationRecord} so the JSON envelope
+ * carries both payloads under one parent.
+ */
+interface ApplyWithSuggestionsProjection {
+    application: applications.JobApplicationRecord;
+    suggestions: applications.SimilarJobAnswerGroup[];
+}
+/**
+ * Action handler for `ttctl jobs apply <id>` (#430).
+ *
+ * Issues the direct `JobApply` mutation via `applications.apply()` (per
+ * ADR-008 § Decision Part 5: the service module is `applications`; the
+ * user-facing verb lives on `jobs`). The handler enforces three
+ * pre-wire gates in order:
+ *
+ *   1. **`--show-questions` preview** — when set, fetches `applyData`
+ *      + `applyQuestions` in parallel and emits the projection;
+ *      returns BEFORE the consent gate (read-only path).
+ *   2. **Consent gate** — `--consent` is REQUIRED per ADR-008 § Decision
+ *      Part 4. Absence raises `CONSENT_REQUIRED` with no wire call
+ *      issued. The service's own runtime check at `apply()` is
+ *      defense-in-depth.
+ *   3. **`--rate` validation** — decimal-string format enforced via
+ *      {@link DECIMAL_PATTERN} (mirrors the `applications confirm`
+ *      pattern). Bad input refuses with `MUTATION_ERROR`.
+ *
+ * `--answers-file` / `--pitch-file` are loaded + wrapper-shape-validated
+ * BEFORE the apply call (mirrors #428 confirm semantics): malformed
+ * JSON or wrong wrapper shape refuses with `VALIDATION_ERROR` and no
+ * mutation is issued.
+ *
+ * **DESTRUCTIVE** — applying to a job creates a `JobApplication`
+ * record. No `withdraw` operation is available on the wire (per ADR-008
+ * § What We're NOT Solving). Prefer `--dry-run` to preview the wire
+ * payload first; the AC scenarios pin the dry-run preview shape.
+ */
+export declare function runJobsApply(id: string, opts: JobsApplyOptions): Promise<void>;
+/**
+ * Render the post-apply `JobApplicationRecord` as the indented entity
+ * preview inside the success-update envelope's pretty block. Pure —
+ * directly unit-testable.
+ *
+ * Fields surfaced: status (value + verbose), requested rate (when
+ * present), the wrapping activity-item id so the user can chain
+ * `applications show <activity-item-id>` to view the new row.
+ */
+export declare function formatJobApplicationRecord(result: applications.JobApplicationRecord): string;
+/**
+ * Render the `--show-questions` projection as a sectioned multi-line
+ * block. Surfaces apply readiness (canApply, applyErrors,
+ * suggestedRate) AND the question inventories so the user can decide
+ * whether to apply AND author the answers-file payload in one glance.
+ *
+ * Each question renders as `  • <identifier>: <prompt>` (mirrors the
+ * `jobs show --with-questions` / #437 format). Empty inventories
+ * surface the zero count in the section header so the user reads
+ * "Toptal returned an empty inventory" rather than "the CLI silently
+ * dropped the section". Pure — directly unit-testable.
+ */
+export declare function formatShowQuestions(projection: ShowQuestionsProjection): string;
+/**
+ * Render the apply-success envelope's pretty body when
+ * `--suggest-answers` was passed alongside the actual apply (#452).
+ * Combines the post-apply `JobApplicationRecord` section with the
+ * advisory suggestion inventory beneath it; the suggestions are
+ * displayed AFTER the apply confirmation so the user reads "apply
+ * succeeded" first and then sees what they could have used.
+ *
+ * Pure — directly unit-testable.
+ */
+export declare function formatApplyWithSuggestions(projection: ApplyWithSuggestionsProjection): string;
+export {};
+//# sourceMappingURL=apply.d.ts.map

package/dist/commands/jobs/apply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../../src/commands/jobs/apply.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAO3C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGxD;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,MAAM,EAAE,YAAY,CAAC;CACtB;AAuCD;;;;;;;;;GASG;AACH,UAAU,uBAAuB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,YAAY,CAAC,UAAU,EAAE,CAAC;IACvC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,cAAc,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC7D,gBAAgB,EAAE,YAAY,CAAC,mBAAmB,EAAE,CAAC;IACrD,kBAAkB,EAAE,YAAY,CAAC,mBAAmB,EAAE,CAAC;IACvD;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,YAAY,CAAC,qBAAqB,EAAE,CAAC;CACpD;AAED;;;;;;;;;GASG;AACH,UAAU,8BAA8B;IACtC,WAAW,EAAE,YAAY,CAAC,oBAAoB,CAAC;IAC/C,WAAW,EAAE,YAAY,CAAC,qBAAqB,EAAE,CAAC;CACnD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAyJpF;AAkMD;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,YAAY,CAAC,oBAAoB,GAAG,MAAM,CAU5F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,uBAAuB,GAAG,MAAM,CA4C/E;AAED;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CAAC,UAAU,EAAE,8BAA8B,GAAG,MAAM,CAa7F"}