@paramour-js/next 0.4.1 → 0.7.0

package/README.md

@@ -3,7 +3,7 @@
 The Next.js integration for [paramour](https://paramour.dev):
 `withTypedRoutes` (build-time registry generation and drift checking),
 typed client hooks for both routers, and the `paramour` CLI
-(`generate` / `check` / `init` / `list` / `doctor`).
+(`generate` / `check` / `init` / `list` / `doctor` / `skills`).
 
 ```sh
 pnpm add paramour @paramour-js/next

package/dist/commands/doctor.d.ts

@@ -1,4 +1,16 @@
 import { type CliIo } from "../cli-io.js";
+/** @internal `paramour doctor` flags — skill-drift test's source of truth. */
+export declare const DOCTOR_OPTIONS: {
+    readonly help: {
+        readonly default: false;
+        readonly short: "h";
+        readonly type: "boolean";
+    };
+    readonly json: {
+        readonly default: false;
+        readonly type: "boolean";
+    };
+};
 /**
  * @internal `paramour doctor` — a verification, so its exit codes follow
  * `check`'s class: 0 pass/warn, 1 any fail, 2 only when doctor itself

package/dist/commands/doctor.js

@@ -6,9 +6,9 @@ const USAGE = [
     "Usage: paramour doctor [options]",
     "",
     "Diagnose the project's paramour setup: config validity, artifact",
-    "freshness, next.config wrapping, version alignment, tsconfig coverage,",
-    "and route-definition discovery (which evaluates matched modules, like",
-    "`paramour list`).",
+    "freshness, next.config wrapping, version alignment, installed agent",
+    "skills, tsconfig coverage, and route-definition discovery (which",
+    "evaluates matched modules, like `paramour list`).",
     "",
     "Exit codes: 0 all checks pass (warnings allowed), 1 any check fails.",
     "",
@@ -16,6 +16,11 @@ const USAGE = [
     "  --help, -h  show this help",
     "  --json      machine-readable output",
 ].join("\n");
+/** @internal `paramour doctor` flags — skill-drift test's source of truth. */
+export const DOCTOR_OPTIONS = {
+    help: { default: false, short: "h", type: "boolean" },
+    json: { default: false, type: "boolean" },
+};
 /**
  * @internal `paramour doctor` — a verification, so its exit codes follow
  * `check`'s class: 0 pass/warn, 1 any fail, 2 only when doctor itself
@@ -23,10 +28,10 @@ const USAGE = [
  */
 export async function runDoctor(argv, io) {
     const { stderr, stdout } = resolveIo(io);
-    const parsed = parseCommandFlags(argv, {
-        help: { default: false, short: "h", type: "boolean" },
-        json: { default: false, type: "boolean" },
-    }, USAGE, { stderr, stdout });
+    const parsed = parseCommandFlags(argv, DOCTOR_OPTIONS, USAGE, {
+        stderr,
+        stdout,
+    });
     if ("exit" in parsed)
         return parsed.exit;
     const flags = parsed.values;

package/dist/commands/generate.d.ts

@@ -1,4 +1,52 @@
 import { type CliIo } from "../cli-io.js";
+/** @internal `paramour check` flags — skill-drift test's source of truth. */
+export declare const CHECK_OPTIONS: {
+    readonly "app-dir": {
+        readonly type: "string";
+    };
+    readonly help: {
+        readonly default: false;
+        readonly short: "h";
+        readonly type: "boolean";
+    };
+    readonly "out-file": {
+        readonly type: "string";
+    };
+    readonly "page-extensions": {
+        readonly type: "string";
+    };
+    readonly "pages-dir": {
+        readonly type: "string";
+    };
+};
+/** @internal `paramour generate` flags — skill-drift test's source of truth. */
+export declare const GENERATE_OPTIONS: {
+    readonly check: {
+        readonly default: false;
+        readonly type: "boolean";
+    };
+    readonly watch: {
+        readonly default: false;
+        readonly type: "boolean";
+    };
+    readonly "app-dir": {
+        readonly type: "string";
+    };
+    readonly help: {
+        readonly default: false;
+        readonly short: "h";
+        readonly type: "boolean";
+    };
+    readonly "out-file": {
+        readonly type: "string";
+    };
+    readonly "page-extensions": {
+        readonly type: "string";
+    };
+    readonly "pages-dir": {
+        readonly type: "string";
+    };
+};
 /**
  * @internal `paramour generate` and its `check` alias, in-process testable:
  * returns the exit code instead of exiting. Codes are grep-style so CI can

package/dist/commands/generate.js

@@ -12,6 +12,14 @@ const SHARED_OPTIONS = {
     "page-extensions": { type: "string" },
     "pages-dir": { type: "string" },
 };
+/** @internal `paramour check` flags — skill-drift test's source of truth. */
+export const CHECK_OPTIONS = SHARED_OPTIONS;
+/** @internal `paramour generate` flags — skill-drift test's source of truth. */
+export const GENERATE_OPTIONS = {
+    ...SHARED_OPTIONS,
+    check: { default: false, type: "boolean" },
+    watch: { default: false, type: "boolean" },
+};
 const SHARED_OPTION_LINES = [
     "  --app-dir <dir>           app directory (default: discovered app/ or src/app/)",
     "  --help, -h                show this help",
@@ -51,11 +59,10 @@ export async function runGenerate(argv, io, mode) {
     const usage = mode === "check" ? CHECK_USAGE : GENERATE_USAGE;
     let flags;
     if (mode === "generate") {
-        const parsed = parseCommandFlags(argv, {
-            ...SHARED_OPTIONS,
-            check: { default: false, type: "boolean" },
-            watch: { default: false, type: "boolean" },
-        }, usage, { stderr, stdout });
+        const parsed = parseCommandFlags(argv, GENERATE_OPTIONS, usage, {
+            stderr,
+            stdout,
+        });
         if ("exit" in parsed)
             return parsed.exit;
         flags = parsed.values;
@@ -63,7 +70,7 @@ export async function runGenerate(argv, io, mode) {
     else {
         // `check` omits --check/--watch entirely: `paramour check --watch`
         // fails as an unknown option, which is the right message for it.
-        const parsed = parseCommandFlags(argv, SHARED_OPTIONS, usage, {
+        const parsed = parseCommandFlags(argv, CHECK_OPTIONS, usage, {
             stderr,
             stdout,
         });

package/dist/commands/init.d.ts

@@ -1,4 +1,44 @@
 import { type CliIo } from "../cli-io.js";
+/** @internal `paramour init` flags — skill-drift test's source of truth. */
+export declare const INIT_OPTIONS: {
+    readonly "dry-run": {
+        readonly default: false;
+        readonly type: "boolean";
+    };
+    readonly force: {
+        readonly default: false;
+        readonly type: "boolean";
+    };
+    readonly help: {
+        readonly default: false;
+        readonly short: "h";
+        readonly type: "boolean";
+    };
+    readonly "no-agents-md": {
+        readonly default: false;
+        readonly type: "boolean";
+    };
+    readonly "no-config": {
+        readonly default: false;
+        readonly type: "boolean";
+    };
+    readonly "no-generate": {
+        readonly default: false;
+        readonly type: "boolean";
+    };
+    readonly "no-script": {
+        readonly default: false;
+        readonly type: "boolean";
+    };
+    readonly "no-skills": {
+        readonly default: false;
+        readonly type: "boolean";
+    };
+    readonly "no-wrap": {
+        readonly default: false;
+        readonly type: "boolean";
+    };
+};
 /**
  * @internal `paramour init` — non-interactive by design: it runs straight
  * through with defaults and prints one status line per step. Exit codes: 0

package/dist/commands/init.js

@@ -5,25 +5,46 @@ import { NoRouteDirsError, resolveInputs } from "../cli-inputs.js";
 import { message, resolveIo } from "../cli-io.js";
 import { CONFIG_FILE_NAMES, loadConfigFile } from "../config.js";
 import { generate } from "../generate.js";
+import { findAgentsFile, upsertAgentsSection } from "../init/agents-md.js";
 import { addPackageScript, checkSetup, paramourConfigTemplate, } from "../init/scaffold.js";
 import { findNextConfig, manualSnippet, wrapNextConfigSource, } from "../init/wrap-next-config.js";
 import { scanRoutes } from "../scan.js";
+import { loadPackagedSkill } from "../skills/packaged.js";
+import { syncTarget } from "../skills/sync.js";
+import { detectTargets } from "../skills/targets.js";
+import { reportOrphans } from "./skills.js";
 const USAGE = [
     "Usage: paramour init [options]",
     "",
     "Set up paramour in this project: scaffold paramour.config.ts, wrap",
-    'next.config with withTypedRoutes, add a "paramour" script, and run the',
-    "first generate. Every step is idempotent and individually skippable.",
+    'next.config with withTypedRoutes, add a "paramour" script, run the',
+    "first generate, install agent skills for detected agent tools, and add",
+    "a paramour section to an existing AGENTS.md/CLAUDE.md. Every step is",
+    "idempotent and individually skippable.",
     "",
     "Options:",
-    "  --dry-run      report every step without writing anything",
-    "  --force        overwrite an existing paramour.config with the scaffold",
-    "  --help, -h     show this help",
-    "  --no-config    skip scaffolding paramour.config.ts",
-    "  --no-generate  skip the first generate",
-    "  --no-script    skip adding the package.json script",
-    "  --no-wrap      skip wrapping next.config",
+    "  --dry-run        report every step without writing anything",
+    "  --force          overwrite an existing paramour.config with the scaffold",
+    "  --help, -h       show this help",
+    "  --no-agents-md   skip the AGENTS.md/CLAUDE.md paramour section",
+    "  --no-config      skip scaffolding paramour.config.ts",
+    "  --no-generate    skip the first generate",
+    "  --no-script      skip adding the package.json script",
+    "  --no-skills      skip installing agent skills",
+    "  --no-wrap        skip wrapping next.config",
 ].join("\n");
+/** @internal `paramour init` flags — skill-drift test's source of truth. */
+export const INIT_OPTIONS = {
+    "dry-run": { default: false, type: "boolean" },
+    force: { default: false, type: "boolean" },
+    help: { default: false, short: "h", type: "boolean" },
+    "no-agents-md": { default: false, type: "boolean" },
+    "no-config": { default: false, type: "boolean" },
+    "no-generate": { default: false, type: "boolean" },
+    "no-script": { default: false, type: "boolean" },
+    "no-skills": { default: false, type: "boolean" },
+    "no-wrap": { default: false, type: "boolean" },
+};
 /**
  * @internal `paramour init` — non-interactive by design: it runs straight
  * through with defaults and prints one status line per step. Exit codes: 0
@@ -33,15 +54,10 @@ const USAGE = [
  */
 export async function runInit(argv, io) {
     const { stderr, stdout } = resolveIo(io);
-    const parsed = parseCommandFlags(argv, {
-        "dry-run": { default: false, type: "boolean" },
-        force: { default: false, type: "boolean" },
-        help: { default: false, short: "h", type: "boolean" },
-        "no-config": { default: false, type: "boolean" },
-        "no-generate": { default: false, type: "boolean" },
-        "no-script": { default: false, type: "boolean" },
-        "no-wrap": { default: false, type: "boolean" },
-    }, USAGE, { stderr, stdout });
+    const parsed = parseCommandFlags(argv, INIT_OPTIONS, USAGE, {
+        stderr,
+        stdout,
+    });
     if ("exit" in parsed)
         return parsed.exit;
     const flags = parsed.values;
@@ -184,6 +200,82 @@ export async function runInit(argv, io) {
             }
         }
     }
+    // 5. Agent skills for detected agent tools. Detection-driven and
+    // non-interactive; init never invents an install location — with no
+    // tooling present, the explicit `paramour skills` command carries the
+    // intent its portable-location fallback needs.
+    if (!flags["no-skills"]) {
+        const detected = detectTargets(projectRoot);
+        if (detected.length === 0) {
+            stdout("  • no agent tooling detected — skipped agent skills (`paramour skills` installs to the portable .agents/skills/)");
+        }
+        else {
+            try {
+                const packaged = loadPackagedSkill();
+                for (const target of detected) {
+                    const result = syncTarget(target, packaged, { dry, force: false });
+                    if (result.written.length > 0) {
+                        stdout(`  ✔ ${dry ? "would install" : "installed"} agent skills → ${target.rel}`);
+                    }
+                    else if (result.skippedModified.length === 0) {
+                        stdout(`  • agent skills already up to date in ${target.rel}`);
+                    }
+                    if (result.skippedModified.length > 0) {
+                        stdout(`  ⚠ ${target.rel}: locally-modified skill files left as-is (\`paramour skills --force\` overwrites)`);
+                    }
+                    // A sync can also delete files (managed orphans from a previous
+                    // install); those must never happen silently, so reuse the exact
+                    // per-orphan wording `paramour skills` prints.
+                    reportOrphans(result, dry, stdout);
+                }
+            }
+            catch (error) {
+                // Same stance as the wrap step: a failed nicety degrades to a
+                // printed pointer, never a failed init.
+                stdout(`  ⚠ could not install agent skills (${message(error)}) — run \`paramour skills\``);
+            }
+        }
+    }
+    // 6. Marker-managed paramour section in AGENTS.md/CLAUDE.md, pointing
+    // agents at the skill step 5 installed. Append-only: init never creates
+    // the file — a root AGENTS.md is a detectTargets signal, so inventing one
+    // would change what the skills step sees on the next run. --force is
+    // deliberately not consulted: the markers delimit paramour-owned content,
+    // so refreshing it is unconditionally safe.
+    if (!flags["no-agents-md"]) {
+        const agentsFile = findAgentsFile(projectRoot);
+        if (agentsFile === undefined) {
+            stdout("  • no AGENTS.md or CLAUDE.md — skipped agents snippet");
+        }
+        else {
+            const name = basename(agentsFile);
+            let source;
+            try {
+                source = readFileSync(agentsFile, "utf8");
+            }
+            catch (error) {
+                // The skills-step stance: a failed nicety never fails init.
+                stdout(`  ⚠ could not read ${name} (${message(error)}) — skipped agents snippet`);
+            }
+            if (source !== undefined) {
+                const result = upsertAgentsSection(source);
+                if (result.status === "added") {
+                    write(agentsFile, result.text);
+                    stdout(`  ✔ ${dry ? "would append" : "appended"} paramour section to ${name}`);
+                }
+                else if (result.status === "updated") {
+                    write(agentsFile, result.text);
+                    stdout(`  ✔ ${dry ? "would update" : "updated"} paramour section in ${name}`);
+                }
+                else if (result.status === "unchanged") {
+                    stdout(`  • ${name} paramour section already up to date — skipped`);
+                }
+                else {
+                    stdout(`  ⚠ ${name} has an unterminated paramour marker — left as-is (remove or close the markers, then re-run)`);
+                }
+            }
+        }
+    }
     return finishWithSummary(projectRoot, artifactPath, stdout);
 }
 function countRoutes(routes) {

package/dist/commands/list.d.ts

@@ -1,4 +1,25 @@
 import { type CliIo } from "../cli-io.js";
+/** @internal `paramour list` flags — skill-drift test's source of truth. */
+export declare const LIST_OPTIONS: {
+    readonly "app-dir": {
+        readonly type: "string";
+    };
+    readonly help: {
+        readonly default: false;
+        readonly short: "h";
+        readonly type: "boolean";
+    };
+    readonly json: {
+        readonly default: false;
+        readonly type: "boolean";
+    };
+    readonly "page-extensions": {
+        readonly type: "string";
+    };
+    readonly "pages-dir": {
+        readonly type: "string";
+    };
+};
 /**
  * @internal `paramour list`: the filesystem scan is authoritative for WHICH
  * routes exist (same engine as generate); discovered definitions overlay

package/dist/commands/list.js

@@ -23,6 +23,14 @@ const USAGE = [
     "  --page-extensions <list>  comma-separated, no leading dots (default: tsx,ts,jsx,js)",
     "  --pages-dir <dir>         pages directory (default: discovered pages/ or src/pages/)",
 ].join("\n");
+/** @internal `paramour list` flags — skill-drift test's source of truth. */
+export const LIST_OPTIONS = {
+    "app-dir": { type: "string" },
+    help: { default: false, short: "h", type: "boolean" },
+    json: { default: false, type: "boolean" },
+    "page-extensions": { type: "string" },
+    "pages-dir": { type: "string" },
+};
 /**
  * @internal `paramour list`: the filesystem scan is authoritative for WHICH
  * routes exist (same engine as generate); discovered definitions overlay
@@ -32,13 +40,10 @@ const USAGE = [
  */
 export async function runList(argv, io) {
     const { stderr, stdout } = resolveIo(io);
-    const parsed = parseCommandFlags(argv, {
-        "app-dir": { type: "string" },
-        help: { default: false, short: "h", type: "boolean" },
-        json: { default: false, type: "boolean" },
-        "page-extensions": { type: "string" },
-        "pages-dir": { type: "string" },
-    }, USAGE, { stderr, stdout });
+    const parsed = parseCommandFlags(argv, LIST_OPTIONS, USAGE, {
+        stderr,
+        stdout,
+    });
     if ("exit" in parsed)
         return parsed.exit;
     const flags = parsed.values;

package/dist/commands/skills.d.ts

@@ -0,0 +1,45 @@
+import { type CliIo } from "../cli-io.js";
+import { type TargetSyncResult } from "../skills/sync.js";
+/** @internal `paramour skills` flags — skill-drift test's source of truth. */
+export declare const SKILLS_OPTIONS: {
+    readonly check: {
+        readonly default: false;
+        readonly type: "boolean";
+    };
+    readonly "dry-run": {
+        readonly default: false;
+        readonly type: "boolean";
+    };
+    readonly force: {
+        readonly default: false;
+        readonly type: "boolean";
+    };
+    readonly help: {
+        readonly default: false;
+        readonly short: "h";
+        readonly type: "boolean";
+    };
+    readonly json: {
+        readonly default: false;
+        readonly type: "boolean";
+    };
+    readonly tool: {
+        readonly multiple: true;
+        readonly type: "string";
+    };
+};
+/**
+ * @internal Per-orphan reporting for a sync: removals (deletions are the one
+ * thing a sync does that must never happen silently) and kept locally-modified
+ * orphans. Shared by `paramour skills` and `paramour init` so the two commands
+ * describe the same operation in the same words.
+ */
+export declare function reportOrphans(result: TargetSyncResult, dry: boolean, stdout: (line: string) => void): void;
+/**
+ * @internal `paramour skills` — the installer for the bundled agent skill.
+ * `--check` follows `check`'s exit class: 1 means "the installed copies do
+ * not reflect the installed package". A plain run treats refusing to clobber
+ * local edits as success (init's manual-fallback precedent): the refusal is
+ * printed, the fix (`--force`) is named, and nothing is broken.
+ */
+export declare function runSkills(argv: readonly string[], io: CliIo): number;