Refactor install flow (#11)

* Refactor install flow and add CLI test

* Bump skillflag to 0.1.1

* Use npx skillflag install in README

* Simplify install heading

* Remove skillflag install note

* Reorder install section and rename migrate

* Remove agent skill bundle section

* Prompt to migrate when install detects violations

* Add installer tests

* Always prompt to add bundled skill

Author: osolmaz

README.md

@@ -4,22 +4,6 @@
 
 SimpleDoc defines a small set of rules for the naming and placement of Markdown files in a codebase, agnostic of any documentation framework.
 
-## Install (Agent Instructions)
-
-Install the bundled agent skill + `AGENTS.md` instructions (no doc migrations):
-
-```bash
-npx -y @simpledoc/simpledoc install
-```
-
-If you prefer to install the skill bundle directly into a repo-scoped Codex skill store:
-
-```bash
-npx -y @simpledoc/simpledoc --skill export simpledoc | skill-install --agent codex --scope repo
-```
-
-(`skill-install` is provided by the `skillflag` package.)
-
 ## Specification
 
 SimpleDoc defines two types of files:
@@ -50,25 +34,23 @@ SimpleDoc defines two types of files:
 - Capitalized files SHOULD be used for general documents that are not tied to a specific time, e.g. `README.md`, `AGENTS.md`, `INSTALL.md`, `HOW_TO_DEBUG.md`.
 - If a capitalized filename has multiple words, it SHOULD use underscores (`CODE_OF_CONDUCT.md`). Dashes are common in the wild but not preferred by this spec.
 
-## Migration
+## Install
 
-Run the migrator from the repo root to rename/move docs and add frontmatter as needed:
+Install the bundled agent skill + `AGENTS.md` instructions (no doc migrations):
 
 ```bash
-npx -y @simpledoc/simpledoc migrate
+npx -y @simpledoc/simpledoc install
 ```
 
-This will start a step-by-step wizard to migrate existing documentation to SimpleDoc and add instructions to `AGENTS.md` to follow it.
-
-### Agent skill bundle
+## Migrate
 
-SimpleDoc ships a bundled `simpledoc` skill for agent instructions. To install it into a repo-scoped Codex skill store:
+Run the migrator from the repo root to rename/move docs and add frontmatter as needed:
 
 ```bash
-npx -y @simpledoc/simpledoc --skill export simpledoc | skill-install --agent codex --scope repo
+npx -y @simpledoc/simpledoc migrate
 ```
 
-(`skill-install` is provided by the `skillflag` package.)
+This will start a step-by-step wizard to migrate existing documentation to SimpleDoc and add instructions to `AGENTS.md` to follow it.
 
 ## CI / Enforcement
 

package-lock.json

@@ -50,7 +50,7 @@
   "dependencies": {
     "@clack/prompts": "^0.11.0",
     "commander": "^11.0.0",
-    "skillflag": "^0.1.0"
+    "skillflag": "^0.1.1"
   },
   "devDependencies": {
     "@eslint/js": "^9.0.0",

package.json

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import process from "node:process";
-import { handleSkillflag } from "skillflag/dist/index.js";
+import { handleSkillflag } from "../cli/skillflag.js";
 
 import { runCli } from "../cli/index.js";
 

src/bin/simpledoc.ts

@@ -0,0 +1,16 @@
+import process from "node:process";
+import { cancel } from "@clack/prompts";
+
+export function abort(message = "Aborted."): void {
+  cancel(message);
+  process.exitCode = 1;
+}
+
+export function getErrorMessage(err: unknown): string {
+  if (err instanceof Error) return err.message;
+  return String(err);
+}
+
+export function hasInteractiveTty(): boolean {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}

src/cli/flow.ts

@@ -0,0 +1,24 @@
+import type { InstallationStatus, InstallAction } from "../installer.js";
+import { buildInstallationActions } from "../installer.js";
+
+export type InstallSelection = {
+  createAgentsFile: boolean;
+  addAttentionLine: boolean;
+  addSkill: boolean;
+};
+
+export function buildDefaultInstallSelection(
+  status: InstallationStatus,
+): InstallSelection {
+  return {
+    createAgentsFile: !status.agentsExists,
+    addAttentionLine: status.agentsExists && !status.agentsHasAttentionLine,
+    addSkill: !status.skillExists,
+  };
+}
+
+export async function buildDefaultInstallActions(
+  status: InstallationStatus,
+): Promise<InstallAction[]> {
+  return buildInstallationActions(buildDefaultInstallSelection(status));
+}

src/cli/install-helpers.ts

@@ -1,5 +1,5 @@
 import process from "node:process";
-import { cancel, intro, outro, spinner } from "@clack/prompts";
+import { intro, outro, spinner } from "@clack/prompts";
 
 import {
   applyInstallationActions,
@@ -9,57 +9,130 @@ import {
 } from "../installer.js";
 import { createGitClient } from "../git.js";
 import type { InstallAction } from "../installer.js";
-import { noteWrapped, promptConfirm } from "./ui.js";
+import {
+  formatActions,
+  planMigration,
+  type FrontmatterAction,
+  type ReferenceUpdateAction,
+  type RenameAction,
+} from "../migrator.js";
+import { buildDefaultInstallActions } from "./install-helpers.js";
+import { abort, getErrorMessage, hasInteractiveTty } from "./flow.js";
+import {
+  MAX_STEP_FILE_PREVIEW_LINES,
+  createScanProgressBarReporter,
+  limitLines,
+  noteWrapped,
+  promptConfirm,
+} from "./ui.js";
+import { runMigrate } from "./migrate.js";
 import { runInstallSteps } from "./steps/install.js";
 
 type InstallOptions = {
   dryRun: boolean;
   yes: boolean;
 };
 
-function abort(message = "Aborted."): void {
-  cancel(message);
-  process.exitCode = 1;
-}
-
-function getErrorMessage(err: unknown): string {
-  if (err instanceof Error) return err.message;
-  return String(err);
-}
-
 function printPreview(actions: InstallAction[]): void {
   process.stdout.write("Planned changes:\n");
   const preview = formatInstallActions(actions).trim();
   if (preview) process.stdout.write(`\n${preview}\n`);
 }
 
+type MigrationInfo = {
+  renames: RenameAction[];
+  frontmatters: FrontmatterAction[];
+  references: ReferenceUpdateAction[];
+  summaryLines: string[];
+  preview: string;
+  hasIssues: boolean;
+};
+
+function buildMigrationInfo(plan: {
+  actions: Array<RenameAction | FrontmatterAction | ReferenceUpdateAction>;
+}): MigrationInfo {
+  const renames = plan.actions.filter(
+    (a): a is RenameAction => a.type === "rename",
+  );
+  const frontmatters = plan.actions.filter(
+    (a): a is FrontmatterAction => a.type === "frontmatter",
+  );
+  const references = plan.actions.filter(
+    (a): a is ReferenceUpdateAction => a.type === "references",
+  );
+
+  const summaryLines: string[] = [];
+  if (renames.length > 0)
+    summaryLines.push(
+      `- Rename/move Markdown files: ${renames.length} file${renames.length === 1 ? "" : "s"}`,
+    );
+  if (frontmatters.length > 0)
+    summaryLines.push(
+      `- Insert YAML frontmatter: ${frontmatters.length} file${frontmatters.length === 1 ? "" : "s"}`,
+    );
+  if (references.length > 0)
+    summaryLines.push(
+      `- Update references to renamed docs: ${references.length} file${references.length === 1 ? "" : "s"}`,
+    );
+
+  const previewLines: string[] = [];
+  if (renames.length > 0) previewLines.push(formatActions(renames));
+  if (frontmatters.length > 0) previewLines.push(formatActions(frontmatters));
+  if (references.length > 0) previewLines.push(formatActions(references));
+  const preview = previewLines.filter(Boolean).join("\n");
+
+  return {
+    renames,
+    frontmatters,
+    references,
+    summaryLines,
+    preview,
+    hasIssues: renames.length + frontmatters.length + references.length > 0,
+  };
+}
+
+function printMigrationSummary(info: MigrationInfo, includePreview: boolean) {
+  if (!info.hasIssues) return;
+  process.stdout.write("SimpleDoc check failed.\n\n");
+  if (info.summaryLines.length > 0) {
+    process.stdout.write(`${info.summaryLines.join("\n")}\n\n`);
+  }
+  if (includePreview && info.preview) {
+    const limited = limitLines(info.preview, MAX_STEP_FILE_PREVIEW_LINES);
+    process.stdout.write(`${limited}\n\n`);
+  }
+}
+
 export async function runInstall(options: InstallOptions): Promise<void> {
   try {
     const git = createGitClient();
     const repoRootAbs = await git.getRepoRoot(process.cwd());
     const installStatus = await getInstallationStatus(repoRootAbs);
 
-    const installActionsAll = await buildInstallationActions({
-      createAgentsFile: !installStatus.agentsExists,
-      addAttentionLine:
-        installStatus.agentsExists && !installStatus.agentsHasAttentionLine,
-      addSkill: !installStatus.skillExists,
+    const hasTty = hasInteractiveTty();
+    const scanProgress = createScanProgressBarReporter(hasTty);
+    const migrationPlan = await planMigration({
+      cwd: repoRootAbs,
+      onProgress: scanProgress,
     });
+    const migrationInfo = buildMigrationInfo(migrationPlan);
 
-    if (installActionsAll.length === 0) {
+    const installActionsAll = await buildDefaultInstallActions(installStatus);
+
+    if (installActionsAll.length === 0 && !migrationInfo.hasIssues) {
       process.stdout.write("No installation needed.\n");
       return;
     }
 
-    const hasTty = Boolean(process.stdin.isTTY && process.stdout.isTTY);
-
     if (options.dryRun) {
-      printPreview(installActionsAll);
+      if (installActionsAll.length > 0) printPreview(installActionsAll);
+      if (migrationInfo.hasIssues) printMigrationSummary(migrationInfo, true);
       return;
     }
 
     if (!hasTty && !options.yes) {
-      printPreview(installActionsAll);
+      if (installActionsAll.length > 0) printPreview(installActionsAll);
+      if (migrationInfo.hasIssues) printMigrationSummary(migrationInfo, true);
       process.stderr.write(
         "\nRefusing to apply changes without a TTY. Re-run with --yes.\n",
       );
@@ -68,39 +141,73 @@ export async function runInstall(options: InstallOptions): Promise<void> {
     }
 
     if (options.yes) {
-      printPreview(installActionsAll);
-      process.stderr.write("Applying changes...\n");
-      await applyInstallationActions(repoRootAbs, installActionsAll);
-      process.stdout.write(
-        "Done. Review with `git status` / `git diff` and commit when ready.\n",
-      );
+      if (installActionsAll.length > 0) {
+        printPreview(installActionsAll);
+        process.stderr.write("Applying changes...\n");
+        await applyInstallationActions(repoRootAbs, installActionsAll);
+      }
+      if (migrationInfo.hasIssues) {
+        printMigrationSummary(migrationInfo, false);
+        process.stdout.write("Run `simpledoc migrate` to fix.\n");
+      } else {
+        process.stdout.write(
+          "Done. Review with `git status` / `git diff` and commit when ready.\n",
+        );
+      }
       return;
     }
 
     intro("simpledoc install");
 
-    const installSel = await runInstallSteps(installStatus);
-    if (installSel === null) return abort("Operation cancelled.");
-
-    const selectedInstallActions = await buildInstallationActions(installSel);
-    if (selectedInstallActions.length === 0) {
-      outro("Nothing selected.");
-      return;
+    if (installActionsAll.length > 0) {
+      const installSel = await runInstallSteps(installStatus);
+      if (installSel === null) return abort("Operation cancelled.");
+
+      const selectedInstallActions = await buildInstallationActions(installSel);
+      if (selectedInstallActions.length > 0) {
+        noteWrapped(
+          formatInstallActions(selectedInstallActions),
+          "Summary of selected changes",
+        );
+
+        const apply = await promptConfirm("Apply these changes now?", true);
+        if (apply === null) return abort("Operation cancelled.");
+        if (!apply) return abort();
+
+        const s = spinner();
+        s.start("Applying changes...");
+        await applyInstallationActions(repoRootAbs, selectedInstallActions);
+        s.stop("Done.");
+      }
     }
 
-    noteWrapped(
-      formatInstallActions(selectedInstallActions),
-      "Summary of selected changes",
-    );
-
-    const apply = await promptConfirm("Apply these changes now?", true);
-    if (apply === null) return abort("Operation cancelled.");
-    if (!apply) return abort();
+    if (migrationInfo.hasIssues) {
+      noteWrapped(
+        migrationInfo.summaryLines.join("\n"),
+        "SimpleDoc check failed",
+      );
+      if (migrationInfo.preview) {
+        const limited = limitLines(
+          migrationInfo.preview,
+          MAX_STEP_FILE_PREVIEW_LINES,
+        );
+        process.stdout.write(`${limited}\n\n`);
+      }
+      const migrateNow = await promptConfirm(
+        "Run `simpledoc migrate` now?",
+        true,
+      );
+      if (migrateNow === null) return abort("Operation cancelled.");
+      if (migrateNow) {
+        await runMigrate({
+          dryRun: false,
+          yes: false,
+          force: false,
+        });
+        return;
+      }
+    }
 
-    const s = spinner();
-    s.start("Applying changes...");
-    await applyInstallationActions(repoRootAbs, selectedInstallActions);
-    s.stop("Done.");
     outro("Review with `git status` / `git diff` and commit when ready.");
   } catch (err) {
     process.stderr.write(`${getErrorMessage(err)}\n`);