@pugi/cli 0.1.0-beta.23 → 0.1.0-beta.24

package/dist/core/repl/init-interview.js

@@ -0,0 +1,457 @@
+/**
+ * `/init` interview orchestrator - 4 phases.
+ *
+ * Inspired by Claude Code's /init slash command (the upstream prompts
+ * the operator across four phases: ask scope → survey codebase →
+ * gap-fill questions → synthesise CLAUDE.md + skills + hooks).
+ * Independent implementation: this module is a pure state machine
+ * that emits the next operator-facing step; the REPL session module
+ * owns the side effects (mounting modals, surfacing the survey
+ * digest, writing PUGI.md and skill scaffolds to disk).
+ *
+ * # Why a state machine
+ *
+ * The four phases need three blocking AskUserQuestion modals (one in
+ * Phase 1 for scope, two in Phase 3 for gap-fill) plus one
+ * synthesise-and-write step in Phase 4. The session module's modal
+ * surface is asynchronous and pull-shaped: it sets `pendingAsk` and
+ * waits for `resolveAsk` to fire. Building the interview as a state
+ * machine that surfaces "what to ask next" / "what to write next"
+ * means the session can drive the modal loop without this module
+ * needing to know about Ink, the SDK transport, or the file writer.
+ *
+ * The machine is deterministic: every transition is a pure function
+ * of the current step + the operator's most recent answer + the
+ * Phase 2 survey result. This makes it trivially testable - the spec
+ * drives the machine to completion without any Ink, fs, or network.
+ *
+ * # Phase summary
+ *
+ *   Phase 1: scope - "Which contexts? PUGI.md / personal / both?" +
+ *            "Skills and hooks? skills only / hooks only / neither?".
+ *   Phase 2: survey - this module's `runSurvey()` calls into the
+ *            codebase-survey helper (a pure fs scan; see that file for
+ *            why we do not spawn a subagent).
+ *   Phase 3: gap-fill - one question for the project codebase practices
+ *            (only if the operator chose project or both) + one
+ *            personal question (only if they chose personal or both).
+ *   Phase 4: synthesise - emit a write plan (a list of {path, body}
+ *            pairs) the session module writes to disk + a list of
+ *            optional skill scaffolds + an optional hooks.json stub.
+ */
+import { signatureForAsk } from './ask.js';
+import { surveyCodebase } from './codebase-survey.js';
+/* ------------------------------------------------------------------ */
+/* Public API                                                          */
+/* ------------------------------------------------------------------ */
+/**
+ * Start a fresh interview. The caller drives the loop by alternating
+ * `nextStep(state)` and `advance(state, answer)` until `state.phase`
+ * becomes `'complete'`.
+ */
+export function startInterview() {
+    return { phase: 'phase1_scope' };
+}
+/**
+ * Compute the next step the session should drive. Pure: returns one
+ * of the seven `NextStep` variants based on the current phase.
+ */
+export function nextStep(state) {
+    switch (state.phase) {
+        case 'phase1_scope':
+            return { kind: 'ask_scope' };
+        case 'phase1_extras':
+            return { kind: 'ask_extras' };
+        case 'phase2_survey':
+            return { kind: 'run_survey' };
+        case 'phase3_project_gap':
+            return { kind: 'ask_project_gap', survey: state.survey };
+        case 'phase3_personal_gap':
+            return { kind: 'ask_personal_gap', survey: state.survey };
+        case 'phase4_synthesise':
+            return {
+                kind: 'synthesise',
+                scope: state.scope,
+                extras: state.extras,
+                survey: state.survey,
+                gaps: state.gaps,
+            };
+        case 'complete':
+            return { kind: 'done', plan: state.plan };
+    }
+}
+/**
+ * Advance the machine one step. Returns the next state. Throws on a
+ * mismatched answer shape (the session module is the only caller and
+ * it always passes the matching variant; a mismatch is a bug, not an
+ * operator-input edge case).
+ */
+export function advance(state, answer) {
+    switch (state.phase) {
+        case 'phase1_scope': {
+            if (answer.kind === 'scope') {
+                return { phase: 'phase1_extras', scope: answer.value };
+            }
+            throw new InterviewMisuseError('phase1_scope expects a scope answer');
+        }
+        case 'phase1_extras': {
+            if (answer.kind === 'extras') {
+                return { phase: 'phase2_survey', scope: state.scope, extras: answer.value };
+            }
+            throw new InterviewMisuseError('phase1_extras expects an extras answer');
+        }
+        case 'phase2_survey': {
+            if (answer.kind === 'survey_result') {
+                // Branch into Phase 3 based on the scope choice. If the
+                // operator picked `personal` only, skip the project-gap
+                // question entirely (the upstream pattern does the same:
+                // "ask only the questions the scope warrants").
+                if (state.scope === 'personal') {
+                    return {
+                        phase: 'phase3_personal_gap',
+                        scope: state.scope,
+                        extras: state.extras,
+                        survey: answer.value,
+                    };
+                }
+                return {
+                    phase: 'phase3_project_gap',
+                    scope: state.scope,
+                    extras: state.extras,
+                    survey: answer.value,
+                };
+            }
+            throw new InterviewMisuseError('phase2_survey expects a survey_result answer');
+        }
+        case 'phase3_project_gap': {
+            if (answer.kind === 'project_gap' || answer.kind === 'skip') {
+                const projectNote = answer.kind === 'project_gap' ? answer.value.trim() : '';
+                // If the scope skipped personal, jump straight to Phase 4.
+                if (state.scope === 'project') {
+                    return {
+                        phase: 'phase4_synthesise',
+                        scope: state.scope,
+                        extras: state.extras,
+                        survey: state.survey,
+                        gaps: { projectNote: projectNote || undefined },
+                    };
+                }
+                return {
+                    phase: 'phase3_personal_gap',
+                    scope: state.scope,
+                    extras: state.extras,
+                    survey: state.survey,
+                    projectNote: projectNote || undefined,
+                };
+            }
+            throw new InterviewMisuseError('phase3_project_gap expects a project_gap or skip answer');
+        }
+        case 'phase3_personal_gap': {
+            if (answer.kind === 'personal_gap' || answer.kind === 'skip') {
+                const personalNote = answer.kind === 'personal_gap' ? answer.value.trim() : '';
+                const gaps = {};
+                if (state.projectNote !== undefined && state.projectNote.length > 0) {
+                    gaps.projectNote = state.projectNote;
+                }
+                if (personalNote.length > 0) {
+                    gaps.personalNote = personalNote;
+                }
+                return {
+                    phase: 'phase4_synthesise',
+                    scope: state.scope,
+                    extras: state.extras,
+                    survey: state.survey,
+                    gaps,
+                };
+            }
+            throw new InterviewMisuseError('phase3_personal_gap expects a personal_gap or skip answer');
+        }
+        case 'phase4_synthesise': {
+            if (answer.kind === 'synthesise_complete') {
+                return { phase: 'complete', plan: answer.value };
+            }
+            throw new InterviewMisuseError('phase4_synthesise expects a synthesise_complete answer');
+        }
+        case 'complete':
+            throw new InterviewMisuseError('interview already complete');
+    }
+}
+/**
+ * Phase 2 worker. Wraps `surveyCodebase` so the session module can
+ * stay symmetric with the modal-driven phases - every phase has a
+ * single helper that turns "current state" into "next answer".
+ */
+export function runSurvey(workspaceRoot) {
+    return surveyCodebase(workspaceRoot);
+}
+/**
+ * Phase 4 worker. Pure: turns the accumulated answers into a write
+ * plan the session module commits. The session is responsible for
+ * actually writing files; this function decides WHAT to write but
+ * never touches the disk.
+ */
+export function synthesise(scope, extras, survey, gaps, paths) {
+    const entries = [];
+    const summaryLines = [];
+    if (scope === 'project' || scope === 'both') {
+        const body = renderPugiMd(survey, gaps);
+        entries.push({
+            kind: 'pugi_md',
+            path: survey.hasExistingPugiMd ? paths.pugiMdProposalPath : paths.pugiMdPath,
+            body,
+        });
+        summaryLines.push(survey.hasExistingPugiMd
+            ? `Proposed PUGI.md updates at ${paths.pugiMdProposalPath} (existing PUGI.md left untouched)`
+            : `Wrote PUGI.md at ${paths.pugiMdPath}`);
+    }
+    if (scope === 'personal' || scope === 'both') {
+        const body = renderPugiLocalMd(gaps);
+        entries.push({
+            kind: 'pugi_local_md',
+            path: paths.pugiLocalMdPath,
+            body,
+        });
+        summaryLines.push(`Wrote PUGI.local.md at ${paths.pugiLocalMdPath}`);
+    }
+    if (extras === 'skills_and_hooks' || extras === 'skills_only') {
+        // Phase 4 default skill proposal: a `verify` skill when the survey
+        // found a test command. The upstream pattern is "propose skills
+        // grounded in what we found"; this is the Pugi minimum that
+        // demonstrates the slot without committing to an opinionated
+        // catalogue. The skill body cites the Phase 2 test command so the
+        // operator can edit it once and have a runnable workflow.
+        if (survey.testCommand) {
+            const skillBody = renderVerifySkill(survey);
+            entries.push({
+                kind: 'skill',
+                name: 'verify',
+                path: paths.skillsDir + '/verify/SKILL.md',
+                body: skillBody,
+            });
+            summaryLines.push(`Scaffolded /verify skill (runs ${survey.packageManager} ${survey.testCommand})`);
+        }
+    }
+    if (extras === 'skills_and_hooks' || extras === 'hooks_only') {
+        if (survey.formatCommand) {
+            const hooksBody = renderHooksJson(survey);
+            entries.push({
+                kind: 'hooks_json',
+                path: paths.hooksJsonPath,
+                body: hooksBody,
+            });
+            summaryLines.push(`Stubbed hooks.json with a PostToolUse format hook (${survey.packageManager} ${survey.formatCommand})`);
+        }
+    }
+    return {
+        scope,
+        extras,
+        survey,
+        entries,
+        summaryLines,
+    };
+}
+/* ------------------------------------------------------------------ */
+/* Question synthesis helpers - the session mounts these as <pugi-ask> */
+/* ------------------------------------------------------------------ */
+/**
+ * Build the Phase 1 scope ask. The session module passes the returned
+ * `AskTag` to the same modal layer that handles persona-emitted asks
+ * so the operator UX is identical across surfaces.
+ *
+ * Returns a structurally valid `AskTag`. Callers may rely on
+ * `signatureForAsk` matching the parser-side hash.
+ */
+export function scopeAskTag() {
+    const question = 'Which PUGI context files should /init set up?';
+    const options = [
+        { value: 'project', label: 'Project PUGI.md', desc: 'Team-shared, checked in' },
+        { value: 'personal', label: 'Personal PUGI.local.md', desc: 'Gitignored, private' },
+        { value: 'both', label: 'Both project + personal', desc: 'Most flexible' },
+    ];
+    return {
+        question,
+        options,
+        signature: signatureForAsk(question, options),
+        start: 0,
+        end: 0,
+    };
+}
+/**
+ * Phase 1 extras ask. Same shape as scope; the session reuses the
+ * `<pugi-ask>` modal.
+ */
+export function extrasAskTag() {
+    const question = 'Also set up skills and hooks?';
+    const options = [
+        { value: 'skills_and_hooks', label: 'Skills + hooks', desc: 'Both surfaces' },
+        { value: 'skills_only', label: 'Skills only', desc: 'On-demand workflows' },
+        { value: 'hooks_only', label: 'Hooks only', desc: 'Deterministic events' },
+        { value: 'neither', label: 'Neither', desc: 'Just PUGI.md' },
+    ];
+    return {
+        question,
+        options,
+        signature: signatureForAsk(question, options),
+        start: 0,
+        end: 0,
+    };
+}
+/**
+ * Phase 3 project gap ask. The question text adapts to whether the
+ * survey found a manifest - when it did the operator is asked about
+ * gotchas; when it did not we ask for the build command outright.
+ *
+ * Two-option `<pugi-ask>` (answer / skip) - the freeform text path is
+ * captured via the modal's "Other" sentinel which the session module
+ * translates into a `project_gap` answer.
+ */
+export function projectGapAskTag(survey) {
+    const question = survey.manifest === 'unknown'
+        ? 'What build/test/lint commands does this repo use?'
+        : 'Any non-obvious gotchas Pugi should know?';
+    const options = [
+        { value: 'answer', label: 'I will type a note', desc: 'Use the Other field below' },
+        { value: 'skip', label: 'Skip', desc: 'Leave PUGI.md minimal' },
+    ];
+    return {
+        question,
+        options,
+        signature: signatureForAsk(question, options),
+        start: 0,
+        end: 0,
+    };
+}
+/**
+ * Phase 3 personal gap ask. Always fixed copy - the upstream pattern
+ * is "ask about THEM, not the codebase" so we keep the question scoped
+ * to operator preferences.
+ */
+export function personalGapAskTag() {
+    const question = 'Anything Pugi should know about you (role, preferences)?';
+    const options = [
+        { value: 'answer', label: 'I will type a note', desc: 'Use the Other field below' },
+        { value: 'skip', label: 'Skip', desc: 'Leave PUGI.local.md minimal' },
+    ];
+    return {
+        question,
+        options,
+        signature: signatureForAsk(question, options),
+        start: 0,
+        end: 0,
+    };
+}
+/* ------------------------------------------------------------------ */
+/* Body renderers                                                      */
+/* ------------------------------------------------------------------ */
+function renderPugiMd(survey, gaps) {
+    const lines = [
+        '# PUGI.md',
+        '',
+        'This file provides guidance to Pugi when working with code in this repository.',
+        '',
+        '## Stack',
+        '',
+    ];
+    if (survey.manifest !== 'unknown') {
+        lines.push(`- Manifest: ${survey.manifest}`);
+    }
+    if (survey.packageManager !== 'unknown') {
+        lines.push(`- Package manager: ${survey.packageManager}`);
+    }
+    if (survey.languages.length > 0) {
+        lines.push(`- Languages: ${survey.languages.join(', ')}`);
+    }
+    lines.push('');
+    lines.push('## Commands');
+    lines.push('');
+    if (survey.buildCommand) {
+        lines.push(`- Build: \`${survey.packageManager} run ${survey.buildCommand}\``);
+    }
+    if (survey.testCommand) {
+        lines.push(`- Test: \`${survey.packageManager} run ${survey.testCommand}\``);
+    }
+    if (survey.lintCommand) {
+        lines.push(`- Lint: \`${survey.packageManager} run ${survey.lintCommand}\``);
+    }
+    if (survey.formatCommand) {
+        lines.push(`- Format: \`${survey.packageManager} run ${survey.formatCommand}\``);
+    }
+    lines.push('');
+    if (gaps.projectNote && gaps.projectNote.length > 0) {
+        lines.push('## Project Notes');
+        lines.push('');
+        lines.push(gaps.projectNote);
+        lines.push('');
+    }
+    lines.push('## Conventions');
+    lines.push('');
+    lines.push('- Generated code, comments, commits, PR text default to English.');
+    lines.push('- Do not add AI Co-Authored-By trailers.');
+    lines.push('- Do not store secrets or credentials in this file.');
+    lines.push('');
+    return lines.join('\n');
+}
+function renderPugiLocalMd(gaps) {
+    const lines = [
+        '# PUGI.local.md',
+        '',
+        'Personal preferences for this project. Gitignored.',
+        '',
+    ];
+    if (gaps.personalNote && gaps.personalNote.length > 0) {
+        lines.push('## About You');
+        lines.push('');
+        lines.push(gaps.personalNote);
+        lines.push('');
+    }
+    else {
+        lines.push('Edit this file to add your role, communication preferences,');
+        lines.push('and any sandbox URLs Pugi should know about.');
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+function renderVerifySkill(survey) {
+    const cmd = `${survey.packageManager === 'unknown' ? 'npm' : survey.packageManager} run ${survey.testCommand ?? 'test'}`;
+    return [
+        '---',
+        'name: verify',
+        'description: Run the project test suite end-to-end and report PASS/FAIL.',
+        '---',
+        '',
+        `Run \`${cmd}\` and report the result. On failure, surface the first failing test name`,
+        'and the file:line so the operator can navigate directly.',
+        '',
+    ].join('\n');
+}
+function renderHooksJson(survey) {
+    const cmd = `${survey.packageManager === 'unknown' ? 'npm' : survey.packageManager} run ${survey.formatCommand ?? 'format'}`;
+    const payload = {
+        schema: 1,
+        hooks: [
+            {
+                event: 'PostToolUse',
+                matcher: 'Write|Edit',
+                command: cmd,
+                description: 'Format edited files after every write.',
+            },
+        ],
+    };
+    return `${JSON.stringify(payload, null, 2)}\n`;
+}
+/* ------------------------------------------------------------------ */
+/* Errors                                                              */
+/* ------------------------------------------------------------------ */
+/**
+ * Thrown when the session module hands the orchestrator an answer
+ * shape that does not match the current phase. This is a programming
+ * bug, not an operator-input edge case - bubbled up so the session
+ * crashes loudly during development rather than silently drifting.
+ */
+export class InterviewMisuseError extends Error {
+    constructor(message) {
+        super(`init-interview: ${message}`);
+        this.name = 'InterviewMisuseError';
+    }
+}
+//# sourceMappingURL=init-interview.js.map