paqad-ai 1.2.0 → 1.2.1

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # paqad-ai
 
+## 1.2.1
+
+### Patch Changes
+
+- [#65](https://github.com/Eliyce/paqad-ai/pull/65) [`f398b00`](https://github.com/Eliyce/paqad-ai/commit/f398b00ced1d676a5e35452a3da7d143431569a0) Thanks [@HLasani](https://github.com/HLasani)! - Fix `paqad-ai onboard` hanging on the RAG "No, skip" path at the end of the full interactive prompt chain.
+
+  The orchestrator previously interleaved the RAG inquirer prompt with file writes: `resolveRagSelection()` ran early, and `writeDetectionReport` / `writeFrameworkMetadata` / `writeOnboardingManifest` / `writeDecisionPauseContractDocument` / `compileRules` / `initializeModuleHealth` / `classifier-config.json` / `next-steps.md` all ran _after_ it. When inquirer left a stuck readline handle on Node's event loop — observed reliably with the full prompt chain on the No-skip branch — every post-RAG write was silently dropped. Users were left with an incomplete `.paqad/**` and no `ONBOARDING COMPLETE` banner.
+
+  Onboarding is now two-phase. Phase 1 writes every core `.paqad/**` artifact and `CLAUDE.md`-equivalents with no inquirer prompts in the path. The new `onPhase1Complete` callback fires only after the onboarding manifest is on disk, so the success banner prints before phase 2 begins. Phase 2 owns the RAG opt-in (prompt → optional index build → idempotent `writeProjectProfile` update). If phase 2 prompts, hangs, fails, or is interrupted, every phase 1 artifact is already durable on disk.
+
+  Adds three orchestrator invariant unit tests that pin the new contract (`onPhase1Complete` fires after all core artifacts exist; a thrown `RagService.configureAndBuild` does not drop core writes; a thrown `resolveRagSelection` does not drop core writes) and a PTY-driven E2E (gated on the system `expect(1)` binary, skipped on platforms without it) that drives the real built CLI through the full interactive Laravel prompt chain, picks "No, skip" on RAG, and asserts the complete `.paqad/**` artifact set on disk.
+
+  Closes [#62](https://github.com/Eliyce/paqad-ai/issues/62).
+
 ## 1.2.0
 
 ### Minor Changes

package/dist/cli/index.js

@@ -22042,7 +22042,33 @@ function toProjectRulePath(source) {
 }
 
 // src/onboarding/orchestrator.ts
+var NEXT_STEPS_MD = [
+  "## Required: Create Documentation Foundation",
+  "",
+  "Before starting feature work, prompt your AI agent with:",
+  "",
+  "```text",
+  "create documentation",
+  "```",
+  "",
+  "This generates:",
+  "- `docs/instructions/**`",
+  "- `docs/instructions/rules/module-map.yml`",
+  "",
+  "Review `docs/instructions/rules/module-map.yml` first. Confirm that module and feature names use business language, then prompt your AI agent with:",
+  "",
+  "```text",
+  "create module documentation",
+  "```",
+  "",
+  "That second prompt generates `docs/modules/**` from the reviewed module map."
+].join("\n");
 var OnboardingOrchestrator = class {
+  /**
+   * Two-phase onboarding. Phase 1 generates and writes every core artifact deterministically,
+   * with no inquirer prompts. Phase 2 is the optional RAG opt-in: it can prompt, fail, or hang
+   * and the project is still fully onboarded. See issue #62 for the regression this protects.
+   */
   async run(options) {
     const detector = new Detector();
     const detection = await detector.detect(options.projectRoot);
@@ -22060,8 +22086,7 @@ var OnboardingOrchestrator = class {
       options.profileOverrides,
       options.projectRoot
     );
-    const ragSelection = await resolveRagSelection(selections.domain, options.selections?.rag);
-    profile.intelligence = applyRagSelection(profile.intelligence, ragSelection);
+    profile.intelligence = applyRagSelection(profile.intelligence, void 0);
     const validator = new SchemaValidator();
     const validation = validator.validate("project-profile", profile);
     const modules = await discoverModules(options.projectRoot);
@@ -22120,17 +22145,6 @@ var OnboardingOrchestrator = class {
     const onboardingWarnings = [];
     writeProjectProfile2(options.projectRoot, profile);
     writeGitignore(options.projectRoot);
-    if (ragSelection?.enabled && ragSelection.provider) {
-      try {
-        await enableRagDuringOnboarding(options.projectRoot, ragSelection);
-      } catch (error) {
-        profile.intelligence = applyRagSelection(profile.intelligence, { enabled: false });
-        writeProjectProfile2(options.projectRoot, profile);
-        onboardingWarnings.push(
-          `RAG setup failed during onboarding: ${error instanceof Error ? error.message : "unknown error"}. Onboarding completed with RAG disabled.`
-        );
-      }
-    }
     writeDetectionReport(options.projectRoot, detection);
     writeFrameworkMetadata(options.projectRoot, VERSION);
     bootstrapFramework(options.projectRoot);
@@ -22213,6 +22227,15 @@ var OnboardingOrchestrator = class {
         `Classifier config initialization failed during onboarding: ${error instanceof Error ? error.message : "unknown error"}.`
       );
     }
+    try {
+      const nextStepsPath = join76(options.projectRoot, ".paqad", "next-steps.md");
+      writeFileSync10(nextStepsPath, NEXT_STEPS_MD);
+      writeResult.written.push(".paqad/next-steps.md");
+    } catch (error) {
+      onboardingWarnings.push(
+        `Next-steps doc write failed: ${error instanceof Error ? error.message : "unknown error"}.`
+      );
+    }
     const manifestPath = writeOnboardingManifest(options.projectRoot, {
       framework_version: VERSION,
       adapter: adapters[0],
@@ -22232,7 +22255,7 @@ var OnboardingOrchestrator = class {
         classifier_config_path: ".paqad/classifier-config.json"
       }
     });
-    return {
+    const phase1Output = {
       adapter: adapters[0],
       decision_pause_supported_adapters: adapters,
       generated_files: writeResult.written.map(toPosixPath),
@@ -22241,6 +22264,27 @@ var OnboardingOrchestrator = class {
       manifest_path: toPosixPath(manifestPath),
       warnings: [...writeResult.skipped, ...drift.review_targets, ...onboardingWarnings]
     };
+    options.onPhase1Complete?.(phase1Output);
+    const ragSelection = await resolveRagSelection(selections.domain, options.selections?.rag);
+    if (ragSelection) {
+      profile.intelligence = applyRagSelection(profile.intelligence, ragSelection);
+      writeProjectProfile2(options.projectRoot, profile);
+    }
+    if (ragSelection?.enabled && ragSelection.provider) {
+      try {
+        await enableRagDuringOnboarding(options.projectRoot, ragSelection);
+      } catch (error) {
+        profile.intelligence = applyRagSelection(profile.intelligence, { enabled: false });
+        writeProjectProfile2(options.projectRoot, profile);
+        onboardingWarnings.push(
+          `RAG setup failed during onboarding: ${error instanceof Error ? error.message : "unknown error"}. Onboarding completed with RAG disabled.`
+        );
+      }
+    }
+    return {
+      ...phase1Output,
+      warnings: [...writeResult.skipped, ...drift.review_targets, ...onboardingWarnings]
+    };
   }
 };
 function buildProjectProfile(selections, snapshot, overrides, projectRoot) {
@@ -27935,7 +27979,7 @@ init_esm_shims();
 init_esm_shims();
 
 // src/index.ts
-var VERSION = "1.2.0";
+var VERSION = "1.2.1";
 
 // src/cli/commands/capabilities.ts
 init_esm_shims();
@@ -29678,8 +29722,6 @@ function parseOptionalInteger(value) {
 
 // src/cli/commands/onboard.ts
 init_esm_shims();
-import { mkdirSync as mkdirSync14, writeFileSync as writeFileSync12 } from "fs";
-import { join as join113 } from "path";
 import { Command as Command7 } from "commander";
 
 // src/cli/ui/banner.ts
@@ -29754,42 +29796,17 @@ function createOnboardCommand() {
           stack: options.stack,
           capabilities: options.capability,
           providers: options.providers
-        } : void 0
+        } : void 0,
+        // Print the success banner as soon as the project is fully written to disk.
+        // The optional RAG phase runs after this and cannot drop core onboarding state
+        // even if it prompts, hangs, or fails. See #62.
+        onPhase1Complete: () => {
+          printNextSteps();
+        }
       });
-      printNextSteps();
-      writeNextStepsFile(options.projectRoot);
     }
   );
 }
-function writeNextStepsFile(projectRoot) {
-  const paqadDir = join113(projectRoot, ".paqad");
-  mkdirSync14(paqadDir, { recursive: true });
-  writeFileSync12(
-    join113(paqadDir, "next-steps.md"),
-    [
-      "## Required: Create Documentation Foundation",
-      "",
-      "Before starting feature work, prompt your AI agent with:",
-      "",
-      "```text",
-      "create documentation",
-      "```",
-      "",
-      "This generates:",
-      "- `docs/instructions/**`",
-      "- `docs/instructions/rules/module-map.yml`",
-      "",
-      "Review `docs/instructions/rules/module-map.yml` first. Confirm that module and feature names use business language, then prompt your AI agent with:",
-      "",
-      "```text",
-      "create module documentation",
-      "```",
-      "",
-      "That second prompt generates `docs/modules/**` from the reviewed module map."
-    ].join("\n"),
-    "utf8"
-  );
-}
 
 // src/cli/commands/plan.ts
 init_esm_shims();
@@ -30384,8 +30401,8 @@ function createRagCommand() {
 // src/cli/commands/refresh.ts
 init_esm_shims();
 import { Command as Command12 } from "commander";
-import { existsSync as existsSync57, readFileSync as readFileSync31, writeFileSync as writeFileSync13 } from "fs";
-import { join as join114 } from "path";
+import { existsSync as existsSync57, readFileSync as readFileSync31, writeFileSync as writeFileSync12 } from "fs";
+import { join as join113 } from "path";
 init_paths();
 init_domain();
 init_project_profile();
@@ -30462,7 +30479,7 @@ async function refreshProviderEntries(projectRoot) {
   writeDecisionPauseContractDocument(projectRoot);
   for (const type of ADAPTER_TYPES) {
     const adapter = AdapterFactory.create(type);
-    const configPath = join114(projectRoot, adapter.getConfigPath());
+    const configPath = join113(projectRoot, adapter.getConfigPath());
     if (!existsSync57(configPath)) {
       continue;
     }
@@ -30478,9 +30495,9 @@ function resolveRefreshStack(value) {
   return value !== void 0 && STACKS.includes(value) ? value : null;
 }
 function writeRefreshDrift(projectRoot, refreshDrift) {
-  const path11 = join114(projectRoot, PATHS.STACK_DRIFT);
+  const path11 = join113(projectRoot, PATHS.STACK_DRIFT);
   const current = readExistingJson(path11);
-  writeFileSync13(path11, `${JSON.stringify({ ...current ?? {}, ...refreshDrift }, null, 2)}
+  writeFileSync12(path11, `${JSON.stringify({ ...current ?? {}, ...refreshDrift }, null, 2)}
 `);
 }
 function readExistingJson(path11) {
@@ -30494,7 +30511,7 @@ function resolveChangedFiles(projectRoot, contextChangedFiles) {
   if (contextChangedFiles.length > 0) {
     return [...new Set(contextChangedFiles)].sort();
   }
-  const trackedPath = join114(projectRoot, PATHS.CHANGED_FILES);
+  const trackedPath = join113(projectRoot, PATHS.CHANGED_FILES);
   if (!existsSync57(trackedPath)) {
     return [];
   }