paperlint 2.0.0

package/dist/init.d.ts

@@ -0,0 +1,201 @@
+import { spawnSync } from "node:child_process";
+import { PROGRAMS } from "./doctor.ts";
+import { type LinkReport } from "./link-skills.ts";
+import { type Merge, type WireResult } from "./hooks-settings.ts";
+import { type PaperFormat } from "./new-paper.ts";
+/** How the papers directory was arrived at. Printed, because a guess must not read as a fact. */
+export type PapersHow = "detected" | "chosen" | "not-asked" | "no-answer" | "guessed";
+/**
+ * WHETHER A HUMAN IS AT THE OTHER END — one decision, made once, with its reason kept, because
+ * every default `init` takes is printed together with WHY nothing was asked.
+ *
+ * clig.dev: "Only use prompts or interactive elements if stdin is an interactive terminal".
+ * stdin alone is not enough: an agent that pipes the output has a TTY-less STDOUT and would
+ * never see the question it is being asked. `CI` covers runners that allocate a pseudo-terminal,
+ * and `--yes` is npm's and create-next-app's way to say "take the defaults" from a terminal.
+ */
+export declare function interactivity({ stdinTTY, stdoutTTY, env, yes, }: {
+    stdinTTY: boolean;
+    stdoutTTY: boolean;
+    env: Readonly<Record<string, string | undefined>>;
+    yes: boolean;
+}): {
+    readonly interactive: boolean;
+    readonly why: string;
+};
+/** The mode of THIS process — the one place `process` is read for it. */
+export declare const processInteractivity: (yes: boolean) => {
+    readonly interactive: boolean;
+    readonly why: string;
+};
+export interface PapersChoice {
+    readonly papers: string;
+    readonly how: PapersHow;
+    readonly candidates: readonly string[];
+}
+/**
+ * One hit is used, several are asked about, none falls back to the documented default — and the
+ * fallback is labelled a guess in the same breath, because the whole class of defect this command
+ * exists to close is a guess that later reads as a measurement.
+ */
+export declare function choosePapers(root: string, { ask, interactive, }: {
+    ask?: (q: string) => Promise<string>;
+    interactive: boolean;
+}): Promise<PapersChoice>;
+export type DeclarationResult = {
+    readonly status: "written";
+    readonly path: string;
+    readonly papers: string;
+    /** The settings were under the old key and were moved to the new one. */
+    readonly migrated: boolean;
+} | {
+    readonly status: "kept";
+    readonly path: string;
+    readonly papers: unknown;
+    readonly migrated: boolean;
+} | {
+    readonly status: "unparsable";
+    readonly path: string;
+    readonly reason: string;
+} | {
+    readonly status: "absent";
+    readonly path: string;
+} | {
+    readonly status: "renamed";
+    readonly path: string;
+    readonly message: string;
+};
+/**
+ * Writes ONE declaration, into the file every channel can already name.
+ *
+ * 🔴 A HOOK CANNOT IMPORT CODE AND CANNOT WALK UP A TREE LOOKING FOR A CONFIG. It can read a path
+ * it is able to spell, and the only path it can always spell is the project's own `package.json`.
+ * That asymmetry is the whole reason the declaration moved here rather than the readers moving to
+ * `rpp.json`: many readers against one (`docs/install.md`, "One declaration").
+ *
+ * ⚠️ Merged, not rewritten, and never over a value the consumer set — an `init` that silently
+ * replaces a setting is worse than an `init` that does nothing, because the consumer keeps
+ * believing the old value.
+ */
+export declare function declarePapers(root: string, papers: string): DeclarationResult;
+export type RppJsonResult = "absent" | "kept" | "filled" | "unparsable";
+/**
+ * `rpp.json` is no longer CREATED — but a consumer who already has one keeps it working, and it
+ * gets the same `papers` value rather than being left to disagree with `package.json` in silence.
+ * Two declarations that disagree is the defect `paperlint doctor` was written to catch; writing the
+ * second one on purpose would be handing it new work.
+ */
+export declare function syncRppJson(root: string, papers: string): RppJsonResult;
+export declare const WORKFLOW_PATH: string;
+/** Where the action is pinned when no release tag is known — obviously a placeholder. */
+export declare const UNPINNED_REF = "<commit-sha>";
+/**
+ * The CI step, as a whole workflow, pinned to `ref` — the release tag of the running package
+ * (`actionRef`). With no tag known (`null`: a git checkout, `npm link`) it keeps the placeholder
+ * and says so: a wrong tag written confidently is worse than a placeholder that is obviously one.
+ */
+export declare function workflowYaml(papers: string, ref: string | null): string;
+export type WorkflowResult = "written" | "kept" | "declined" | "not-asked";
+export declare function offerWorkflow(root: string, papers: string, { ask, interactive, version, }: {
+    ask?: (q: string) => Promise<string>;
+    interactive: boolean;
+    /** The running package's version; see `InitOptions.version`. */
+    version?: string;
+}): Promise<WorkflowResult>;
+/** What `init` says about the CI workflow — and, when none was written, the step to paste. */
+export declare function reportWorkflow(wf: WorkflowResult, { version, papersDir, why, }: {
+    version?: string;
+    papersDir: string;
+    why: string;
+}): string[];
+/**
+ * The external toolchain is REPORTED, never fetched. Each entry already carries what goes quiet
+ * without it, which is the only reason the list is worth printing: a missing checker and a
+ * passing checker produce the same silence.
+ */
+export declare function missingPrograms(run?: typeof spawnSync): readonly (typeof PROGRAMS)[number][];
+/**
+ * What is left after `init` — commands only, all typed in the same terminal.
+ *
+ * 🔴 THE TWO `/plugin` LINES ARE GONE, AND THAT WAS THE POINT. They were the one step "that cannot
+ * be done from a terminal": typed into another program, invisible to `paperlint doctor`, impossible for
+ * an agent installing this package, and (as a repository-declared plugin) not installed in a cloud
+ * session at all. `init` now writes the same three hook commands into `.claude/settings.json`
+ * itself (`hooks-settings.ts`), so there is nothing left to type anywhere but here.
+ */
+export declare function nextSteps(papersDir?: string): string;
+export type HooksOutcome = WireResult | {
+    readonly status: "skipped";
+} | {
+    readonly status: "declined";
+} | {
+    readonly status: "failed";
+    readonly reason: string;
+};
+/**
+ * The hooks step: decide, then wire. `hooks: false` is `--no-hooks`. The default without a human
+ * is YES — installing a package whose purpose includes an edit guard makes "yes" guessable, and
+ * the edit is idempotent and shows up in `git diff` (the rule `docs/install.md` took from
+ * Playwright: ask only about what cannot be guessed or is expensive).
+ */
+export declare function offerHooks(root: string, { hooks, interactive, ask, merge, }: {
+    hooks: boolean;
+    interactive: boolean;
+    ask?: (q: string) => Promise<string>;
+    merge?: Merge;
+}): Promise<HooksOutcome>;
+/** The hooks section of init's report. Every default names the flag that changes it. */
+export declare function reportHooks(outcome: HooksOutcome, { how, here }: {
+    how: string;
+    here: (p: string) => string;
+}): string[];
+/**
+ * The skills section of init's report: what was linked, what already was, and — BY NAME — what
+ * was left alone. A skipped entry does not fail init: the name is taken by something the consumer
+ * made, replacing it would be worse than not linking, and doctor's report below repeats the gap.
+ */
+export declare function reportSkillLinks(report: LinkReport, here: (p: string) => string): string[];
+export interface InitOptions {
+    log?: typeof console.log;
+    err?: typeof console.error;
+    cwd?: string;
+    /** Asks one question. Injected so the prompt is assertable without a pseudo-terminal. */
+    ask?: (question: string) => Promise<string>;
+    /**
+     * Whether a human is at the other end. Defaults to `interactivity()` over this process: stdin
+     * AND stdout are terminals, `CI` is unset, and no `--yes`.
+     */
+    interactive?: boolean;
+    /** `--yes`: take every default without asking. */
+    yes?: boolean;
+    /** `false` is `--no-hooks`. */
+    hooks?: boolean;
+    /** vigiles' merge. Injected only so a test can observe or replace it. */
+    merge?: Merge;
+    /** `--paper <name>`: create this paper, even without a terminal. */
+    paper?: string | null;
+    /** `--format tex|md` for that paper. */
+    format?: PaperFormat | null;
+    /**
+     * Creates one paper and lints it — `paperlint new`'s own routine, passed in by the CLI so `init` and
+     * `new` cannot drift into two implementations.
+     */
+    createPaper?: (papersRoot: string, name: string, format: PaperFormat) => Promise<number>;
+    run?: typeof spawnSync;
+    /**
+     * What `paperlint lint` would resolve from the declaration, asked of the CLI's OWN reader. A second
+     * implementation here would be a second source of truth — the very defect `doctor` reports.
+     */
+    resolveCliPapers?: (root: string) => string | null;
+    /** Links the skills. Injected only so a test can stand in for the installed package. */
+    link?: (root: string) => LinkReport;
+    /**
+     * The version of the running package, read by the CLI from its own `package.json`. The CI
+     * workflow is pinned to its release tag (`actionRef`); absent or unreleased, the placeholder.
+     */
+    version?: string;
+}
+/** Reads one line from a real terminal. Kept out of `init` so the command stays testable. */
+export declare function askOnTerminal(question: string): Promise<string>;
+export declare function init(dir: string, opts?: InitOptions): Promise<number>;
+//# sourceMappingURL=init.d.ts.map

package/dist/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"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"}