@cluesmith/codev 3.3.5 → 3.3.7

package/dist/commands/bootstrap-docs.d.ts

@@ -0,0 +1,132 @@
+/**
+ * `codev bootstrap-docs` (Spec 1797): draft the four governance docs from an existing
+ * codebase, in place of the starter placeholders `codev adopt` leaves behind.
+ *
+ * The CLI owns everything deterministic: which files are still untouched starters, whether
+ * there is anything to document, the launch, the before/after change report, validation of
+ * the drafts and the summary. The agent owns only the writing, under the rules of the
+ * `update-arch-docs` skill's bootstrap mode: the project's installed copy when it matches
+ * the package (#1811), the packaged text inlined into the prompt otherwise.
+ *
+ * An interactive agent cannot be sandboxed from here, so the guarantee is detect-and-report:
+ * anything that moved outside the eligible files is named and the exit code is non-zero.
+ * Nothing is ever reverted, staged or committed; the drafts are the human's to review.
+ */
+import { type AgentExit, type AgentLaunch } from '../lib/agent-process.js';
+import { type GovernanceStatus, type Violation } from '../lib/governance-bootstrap.js';
+import { type IdentityChange } from '../lib/tree-snapshot.js';
+import { type InteractiveTaskLauncher } from '../agent-farm/utils/harness.js';
+import { type SkillProvider } from '../lib/skill-refresh.js';
+export type { AgentExit, AgentLaunch };
+/** Where the rendered prompt is saved, for the manual fallback and for the record. */
+export declare const PROMPT_FILE = ".consult/bootstrap-docs/prompt.md";
+/** Where the draft review's prompt and each reviewer's feedback are written. */
+export declare const REVIEW_DIR = ".consult/bootstrap-docs";
+export declare const REVIEW_PROMPT_FILE = ".consult/bootstrap-docs/review-prompt.md";
+/** The three reviewers of the drafts, run in parallel. */
+export declare const REVIEW_MODELS: readonly ["gemini", "codex", "claude"];
+/**
+ * Largest prompt passed as a command-line argument. Linux caps one argument at 128 KB
+ * (MAX_ARG_STRLEN); above this the prompt goes to the manual fallback instead of failing
+ * the spawn with E2BIG.
+ */
+export declare const MAX_PROMPT_BYTES = 100000;
+export interface BootstrapDocsOptions {
+    /** Project root; defaults to the current directory. */
+    cwd?: string;
+    /** Report eligibility and the resolved launch, launch nothing, write nothing. */
+    dryRun?: boolean;
+}
+/** Seams for tests: the agent, the prompt and the environment are all replaceable. */
+export interface BootstrapDocsDeps {
+    /** Root of the packaged skeleton (holds `templates/` and the skill copies). */
+    skeletonDir: string;
+    resolveLauncher(root: string): InteractiveTaskLauncher;
+    isExecutableAvailable(executable: string): boolean;
+    confirm(question: string): Promise<boolean>;
+    stdinIsTTY: boolean;
+    spawnAgent(launch: AgentLaunch, cwd: string): Promise<AgentExit>;
+    /** Run `consult` with these arguments in `cwd` and wait for it. */
+    runConsult(args: string[], cwd: string): Promise<AgentExit>;
+    log(line: string): void;
+}
+export type BootstrapOutcome = 'no-codev' | 'nothing-eligible' | 'empty-repo' | 'dry-run' | 'manual' | 'declined' | 'unsafe-path' | 'ran';
+export type FileStatus = GovernanceStatus;
+export interface DraftValidation {
+    name: string;
+    /** `unwritten`: still a placeholder after the session; `deleted`: the file is gone. */
+    state: 'written' | 'unwritten' | 'deleted';
+    violations: Violation[];
+    /** Cold sections the map leaves out, listed as information when the cold doc has > 12. */
+    unmappedInfo: string[];
+}
+export interface OutOfScopeChange {
+    path: string;
+    annotation?: string;
+}
+export interface ChangeReport {
+    /** Governance files that were not eligible but changed (curated, missing, held back). */
+    governanceChanged: string[];
+    identityChanges: IdentityChange[];
+    indexChanged: boolean;
+    outOfScope: OutOfScopeChange[];
+    /** Set when the tree could be read before the session and not after. */
+    detectionLost?: string;
+    /** The detector's scope, stated in every summary. */
+    scope: string;
+}
+export type ReviewStatus = 'ok' | 'skipped' | 'failed';
+export interface ReviewOutcome {
+    model: string;
+    status: ReviewStatus;
+    /** Why a reviewer was skipped or failed. */
+    detail?: string;
+}
+export interface DraftReview {
+    /** Nothing was written, so nothing was reviewed. */
+    ran: boolean;
+    /** Why the review did not run: `consult` could not start, or the review could not be prepared. */
+    unavailable?: string;
+    reviewers: ReviewOutcome[];
+    /** Governance files whose content changed while the reviewers ran. */
+    changesDuringReview?: ChangeReport;
+}
+export interface BootstrapDocsResult {
+    exitCode: number;
+    outcome: BootstrapOutcome;
+    files: FileStatus[];
+    launched: boolean;
+    agentExit?: AgentExit;
+    report?: ChangeReport;
+    validation?: DraftValidation[];
+    review?: DraftReview;
+}
+/**
+ * Fill `{{NAME}}` placeholders in one pass, so text inserted for one placeholder (the skill
+ * text in particular) is never itself scanned for placeholders.
+ */
+export declare function renderPrompt(template: string, values: Record<string, string>): string;
+/** Where the agent gets the bootstrap-mode rules from. */
+export type SkillSource = {
+    kind: 'installed';
+    dir: string;
+}
+/** `provider` names the launching harness's copy to inline; a manual prompt has none. */
+ | {
+    kind: 'inline';
+    reason: string;
+    provider?: SkillProvider;
+};
+/**
+ * Run the project's installed skill by name when the launching harness loads it and the copy
+ * is identical to the package's, so the rules the agent follows are exactly the ones the
+ * drafts are validated against. Anything else gets the packaged text inlined.
+ */
+export declare function chooseSkillSource(root: string, skeletonDir: string, harnessName: string | undefined): SkillSource;
+export declare function describeSkillSource(source: SkillSource): string;
+/** The argv for one reviewer: general mode, so no project detection is needed. */
+export declare function reviewConsultArgs(model: string): string[];
+export declare function runBootstrapDocs(options?: BootstrapDocsOptions, overrides?: Partial<BootstrapDocsDeps>): Promise<BootstrapDocsResult>;
+/** CLI entry: run the pass and hand back the process exit code. */
+export declare function bootstrapDocs(options?: BootstrapDocsOptions): Promise<number>;
+//# sourceMappingURL=bootstrap-docs.d.ts.map

package/dist/commands/bootstrap-docs.d.ts.map

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